Confirmar Sincronização

Endpoint para confirmar que o ERP processou com sucesso os produtos de um lote.

Informações do Endpoint

Atributo	Valor
Método	POST
URL	/fiscal/confirmar-sincronizacao
Content-Type	application/json
Autenticação	Headers customizados
Função	Liberar próximo lote de produtos

---

Headers de Autenticação

Header	Tipo	Obrigatório	Descrição
empresa-id	integer	Sim	ID da empresa na plataforma Nacional Tax
token-api	string	Sim	Token de autenticação do cliente
cnpj	string	Sim	CNPJ da empresa (apenas números)
regime-tributario	string	Sim	Regime tributário (SN, LP, LR)

---

Request Body

Estrutura

{
  "lote_id": "lote-20250112-143022-a1b2c3d4"
}

Campos do Request

Campo	Tipo	Obrigatório	Descrição
lote_id	string	Sim	ID do lote recebido no endpoint de produtos revisados

Dica

O lote_id é retornado no endpoint Produtos Revisados.

---

Response

Sucesso (200 OK)

{
  "status": "confirmado",
  "lote_id": "lote-20250112-143022-a1b2c3d4",
  "quantidade_confirmada": 100
}

Campos do Response

Campo	Tipo	Descrição
status	string	Status da confirmação (sempre "confirmado" em caso de sucesso)
lote_id	string	ID do lote confirmado
quantidade_confirmada	integer	Quantidade de produtos sincronizados

---

Erros Possíveis

400 Bad Request

Causa: Dados inválidos ou campo lote_id ausente

{
  "detail": [
    {
      "loc": ["body", "lote_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

401 Unauthorized

Causa: Headers de autenticação inválidos

{
  "detail": "Cliente não autorizado"
}

404 Not Found

Causa: Lote não encontrado, já confirmado ou não pertence ao cliente

{
  "detail": "Lote não encontrado ou já confirmado"
}

Possíveis motivos:

• Lote já foi confirmado anteriormente
• lote_id inválido ou inexistente
• Lote pertence a outro cliente
• Lote não está com status EM_LOTE

500 Internal Server Error

Causa: Erro interno do servidor

{
  "detail": "Erro ao processar requisição. Contate o suporte."
}

---

Exemplo Completo

Request

curl -X POST "https://api.nacionaltax.com.br/fiscal/confirmar-sincronizacao" \
  -H "Content-Type: application/json" \
  -H "empresa-id: 1" \
  -H "token-api: seu-token-aqui" \
  -H "cnpj: 12345678000199" \
  -H "regime-tributario: SN" \
  -d '{
  "lote_id": "lote-20250112-143022-a1b2c3d4"
}'

Response

{
  "status": "confirmado",
  "lote_id": "lote-20250112-143022-a1b2c3d4",
  "quantidade_confirmada": 100
}

---

Fluxo de Confirmação

---

Regras de Negócio

1. Validações

A API valida:

• ✅ Lote existe no sistema
• ✅ Lote pertence ao cliente autenticado
• ✅ Lote está com status EM_LOTE
• ✅ Lote não foi confirmado anteriormente

Importante

Um lote só pode ser confirmado uma única vez. Tentativas subsequentes retornarão erro 404.

2. Transação Atômica

A confirmação é processada em uma transação de banco de dados:

• Sucesso: Todos os produtos do lote passam para SINCRONIZADO
• Erro: Nenhum produto é atualizado (rollback)

3. Liberação de Novo Lote

Após a confirmação bem-sucedida:

• ✅ Produtos confirmados não aparecem mais nas consultas
• ✅ Próximo lote pode ser solicitado imediatamente
• ✅ Novos produtos PENDENTES podem entrar no próximo lote

4. Idempotência

Atenção

Este endpoint NÃO é idempotente. Cada confirmação altera o estado dos produtos de forma permanente.

Recomendação: Implemente controle no seu ERP para evitar confirmações duplicadas.

---

Estados dos Produtos

Antes da Confirmação

PENDENTE (produtos novos, aguardando lote)
   ↓
EM_LOTE (produtos no lote atual, aguardando confirmação)

Após a Confirmação

SINCRONIZADO (produtos confirmados, não aparecem mais nas consultas)
   ↓
Liberado para novo lote com produtos PENDENTES

---

Exemplo de Integração Completa

Python

import requests
import time

# Configuração
base_url = "https://api.nacionaltax.com.br"
headers = {
    "Content-Type": "application/json",
    "empresa-id": "1",
    "token-api": "seu-token-aqui",
    "cnpj": "12345678000199",
    "regime-tributario": "SN"
}

# Filtros para busca
filtros = {
    "operacao": "S",
    "consumidor_final": False,
    "natureza_operacao_id": 2,
    "destinatario": {
        "cnae": "4646-0/02",
        "contrib_icms": True,
        "contrib_ipi": True,
        "regime_icms": 1,
        "regime_pis_cofins": 2,
        "uf": "SP"
    }
}

def processar_lote():
    # 1. Buscar produtos revisados
    print("1. Buscando produtos revisados...")
    response = requests.post(
        f"{base_url}/fiscal/produtos-revisados?limit=100",
        headers=headers,
        json=filtros
    )
    
    if response.status_code != 200:
        print(f"Erro ao buscar produtos: {response.status_code}")
        return False
    
    data = response.json()
    lote_id = data["lote_id"]
    quantidade = data["quantidade"]
    
    print(f"✓ Lote recebido: {lote_id}")
    print(f"✓ Quantidade: {quantidade} produtos")
    
    # 2. Processar produtos no ERP
    print("\n2. Processando produtos no ERP...")
    for produto in data["produtos"]:
        for item in produto["itens"]:
            # Seu código de importação aqui
            print(f"  - Processando NCM: {item['ncm']}")
            time.sleep(0.1)  # Simula processamento
    
    print("✓ Todos os produtos processados")
    
    # 3. Confirmar recebimento
    print("\n3. Confirmando recebimento...")
    response = requests.post(
        f"{base_url}/fiscal/confirmar-sincronizacao",
        headers=headers,
        json={"lote_id": lote_id}
    )
    
    if response.status_code == 200:
        confirmacao = response.json()
        print(f"✓ Confirmado: {confirmacao['quantidade_confirmada']} produtos")
        return True
    else:
        print(f"✗ Erro na confirmação: {response.status_code}")
        print(response.json())
        return False

# Executar
if __name__ == "__main__":
    sucesso = processar_lote()
    if sucesso:
        print("\n✓ Processo concluído com sucesso!")
    else:
        print("\n✗ Processo falhou. Verifique os logs.")

C#

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class NacionalTaxClient
{
    private readonly HttpClient _httpClient;
    private const string BaseUrl = "https://api.nacionaltax.com.br";
    
    public NacionalTaxClient(string empresaId, string tokenApi, string cnpj, string regimeTributario)
    {
        _httpClient = new HttpClient();
        _httpClient.DefaultRequestHeaders.Add("empresa-id", empresaId);
        _httpClient.DefaultRequestHeaders.Add("token-api", tokenApi);
        _httpClient.DefaultRequestHeaders.Add("cnpj", cnpj);
        _httpClient.DefaultRequestHeaders.Add("regime-tributario", regimeTributario);
    }
    
    public async Task<bool> ConfirmarSincronizacao(string loteId)
    {
        var payload = new { lote_id = loteId };
        var json = JsonSerializer.Serialize(payload);
        var content = new StringContent(json, Encoding.UTF8, "application/json");
        
        var response = await _httpClient.PostAsync(
            $"{BaseUrl}/fiscal/confirmar-sincronizacao",
            content
        );
        
        if (response.IsSuccessStatusCode)
        {
            var result = await response.Content.ReadAsStringAsync();
            Console.WriteLine($"Confirmação bem-sucedida: {result}");
            return true;
        }
        else
        {
            Console.WriteLine($"Erro: {response.StatusCode}");
            var error = await response.Content.ReadAsStringAsync();
            Console.WriteLine(error);
            return false;
        }
    }
}

// Uso
var client = new NacionalTaxClient("1", "seu-token", "12345678000199", "SN");
await client.ConfirmarSincronizacao("lote-20250112-143022-a1b2c3d4");

---

Boas Práticas

✅ Fazer

1. Confirmar Apenas Após Sucesso:

   • Processe todos os produtos do lote
   • Valide a integridade dos dados
   • Só então confirme o recebimento

2. Armazenar lote_id:

   • Guarde o lote_id em um log ou banco de dados
   • Útil para rastreabilidade e auditoria

3. Tratamento de Erros:

   • Implemente retry com backoff exponencial
   • Registre todas as tentativas de confirmação
   • Monitore falhas recorrentes

4. Validação Prévia:

   • Verifique se todos os produtos foram importados
   • Valide se as tributações foram aplicadas
   • Confirme integridade dos dados

❌ Evitar

1. Confirmação Prematura:

   • Não confirme antes de processar todos os produtos
   • Produtos confirmados não podem ser recuperados

2. Múltiplas Confirmações:

   • Não tente confirmar o mesmo lote várias vezes
   • Implemente controle de duplicação no seu sistema

3. Ignorar Erros:

   • Não ignore erros de confirmação
   • Sempre trate exceções adequadamente

4. Processar Sem Confirmar:

   • Sempre confirme após processar com sucesso
   • Caso contrário, o mesmo lote será retornado indefinidamente

---

Troubleshooting

Problema: Erro 404 ao Confirmar

Possíveis Causas:

1. Lote já foi confirmado anteriormente
2. lote_id inválido
3. Timeout entre busca e confirmação (lote expirou)

Solução:

• Verifique se o lote_id está correto
• Consulte seus logs para ver se não houve confirmação anterior
• Solicite novo lote se necessário

Problema: Mesmo Lote Retornando Repetidamente

Causa: Lote não foi confirmado

Solução:

1. Confirme o lote atual usando este endpoint
2. Aguarde resposta 200 OK
3. Solicite novo lote

Problema: Quantidade Confirmada Diferente do Esperado

Causa: Alguns produtos podem ter sido processados em outro sistema

Solução:

• Compare a quantidade_confirmada com o esperado
• Investigue discrepâncias
• Entre em contato com o suporte se necessário

---

Próximos Passos

Após confirmar o lote:

1. Solicitar Próximo Lote:

   • Use o endpoint Produtos Revisados
   • Com os mesmos filtros ou filtros diferentes
   • Processo se repete

2. Monitorar Sincronização:

   • Implemente logs de confirmação
   • Monitore quantidade de produtos sincronizados
   • Acompanhe tempo de processamento

3. Automatizar Processo:

   • Configure jobs/schedulers no seu ERP
   • Automatize busca → processamento → confirmação
   • Implemente alertas para falhas

---

Ver Também

• Enviar Produtos - Como enviar produtos para análise
• Produtos Revisados - Como buscar produtos revisados
• Tabelas de Referência - Valores auxiliares para integração