Tracking API

⚠️ Aviso de Deprecação O endpoint /v1/tracking/events está depreciado. Utilize /v2/tracking/events. Integrações existentes em v1 continuam funcionando, mas novas devem usar v2.

Endpoint

POST /v2/tracking/events

QA — supply-api-gw.qa.arcocv.co STAGE — supply-api-gw.stage.arcocv.co PROD — tracking.arcoeducacao.com.br

Autenticação

🔑 Chave de API obrigatória Envie sua chave via header: x-api-key: <api_key>

Body da Requisição application/json

Todos os campos de data/hora devem estar em ISO 8601 com uma zona horária explícita: sufixo UTC Z (ex: 2024-09-19T15:34:56Z) ou offset ±HH:MM (ex: 2024-09-19T12:34:56-03:00). Valores sem Z ou offset serão rejeitados pela API.

Campo	Tipo	Descrição
data_geracao_eventoobrigatório	string	Data e hora de geração do evento em formato ISO 8601 (deve incluir `Z` ou offset). ex: `2024-09-19T12:34:56-03:00`
transportadoraobrigatório	string	Nome da transportadora. ex: `NOME_TRANSPORTADORA`
cnpj_transportadoraobrigatório	string	CNPJ da transportadora (14 dígitos, somente números). ex: `12345678901234`
nota_fiscalobrigatório	string	Número da Nota Fiscal relacionada ao envio. ex: `123456`
emissao_conhecimentoobrigatório	string	Data de emissão do Conhecimento de Transporte em ISO 8601 (deve incluir `Z` ou offset). ex: `2024-09-18T10:20:30-03:00`
remetenteobrigatório	object	Informações do remetente. Veja os campos aninhados abaixo.
↳ campos de remetente
nomeobrigatório	string	Nome do remetente. ex: `SAE`
cnpjobrigatório	string	CNPJ do remetente (14 dígitos). ex: `98765432000100`
previsao_de_entrega	string \| null	Data e hora estimada de entrega em ISO 8601 (deve incluir `Z` ou offset). Omita o campo ou envie `null` se não disponível. ex: `2024-03-26T16:15:27-03:00`
data_de_entrega	string \| null	Data e hora efetiva de entrega em ISO 8601 (deve incluir `Z` ou offset) quando a entrega é concluída. Se não houver entrega ainda, envie `null` ou omita este campo — ambos são aceitos. ex: `2024-03-27T16:15:27-03:00`
statusobrigatório	string	Descrição do status de entrega legível por humanos. ex: `ENTREGA REALIZADA NORMALMENTE`
codigo_statusobrigatório	string	Código PROCEDA/OCOREN do status (padrão de mercado, 00–99). Consulte a tabela de códigos abaixo. ex: `01`
eventsobrigatório	array of objects	Lista de todos os eventos de rastreamento para este envio. Veja os campos aninhados abaixo.
↳ campos de events[ ]
data_horaobrigatório	string	Data e hora do evento em ISO 8601 (deve incluir `Z` ou offset). ex: `2024-03-20T17:38:36-03:00`
codigoobrigatório	string	Código PROCEDA/OCOREN do evento (padrão de mercado, 00–99). Consulte a tabela de códigos abaixo. ex: `40`
descricao_codigo	string	Opcional. Rótulo textual do código PROCEDA/OCOREN. ex: `EM ROTA`
descricaoobrigatório	string	Descrição completa e legível por humanos do evento. ex: `Mercadoria saiu para entrega - Placa CLF9G72`

Exemplo de Requisição

{
  "data_geracao_evento": "2024-09-19T12:34:56-03:00",
  "transportadora": "NOME_TRANSPORTADORA",
  "cnpj_transportadora": "12345678901234",
  "nota_fiscal": "123456",
  "emissao_conhecimento": "2024-09-18T10:20:30-03:00",
  "remetente": {
    "nome": "SAE",
    "cnpj": "98765432000100"
  },
  "previsao_de_entrega": "2024-03-26T16:15:27-03:00",
  "data_de_entrega": "2024-03-27T16:15:27-03:00",
  "status": "ENTREGA REALIZADA NORMALMENTE",
  "codigo_status": "1",
  "events": [
    {
      "data_hora": "2024-03-20T17:38:36-03:00",
      "codigo": "00",
      "descricao_codigo": "PROCESSO DE TRANSPORTE JÁ INICIADO",
      "descricao": "Mercadoria coletada no remetente"
    },
    {
      "data_hora": "2024-03-26T16:15:27-03:00",
      "codigo": "1",
      "descricao_codigo": "ENTREGA REALIZADA NORMALMENTE",
      "descricao": "Entrega efetuada com sucesso"
    }
  ]
}

Responses

202

Accepted — Requisição recebida com sucesso e será processada de forma assíncrona.

401

Unauthorized — Chave de API ausente ou inválida.

422

Unprocessable Entity — Um ou mais campos obrigatórios estão ausentes ou com valores inválidos.

500

Internal Server Error — Um erro inesperado ocorreu no servidor.

Códigos PROCEDA/OCOREN

PROCEDA/OCOREN é o padrão de mercado brasileiro para eventos logísticos. Utilize esses códigos nos campos codigo_status e events[].codigo.

Código	Descrição
00	Processo de Transporte já Iniciado
01	Entrega Realizada Normalmente
02	Entrega Fora da Data Programada
03	Recusa por Falta de Pedido de Compra
04	Recusa por Pedido de Compra Cancelado
05	Falta de Espaço Físico no Depósito do Cliente Destino
06	Endereço do Cliente Destino não Localizado
07	Devolução não Autorizada pelo Cliente
08	Preço Mercadoria em Desacordo com o Pedido Compra
09	Mercadoria em Desacordo com o Pedido Compra
10	Cliente Destino somente Recebe Mercadoria com Frete Pago
11	Recusa por Deficiência Embalagem Mercadoria
12	Redespacho não Indicado
13	Transportadora não Atende a Cidade do Cliente Destino
14	Mercadoria Sinistrada
15	Embalagem Sinistrada
16	Pedido de Compras em Duplicidade
17	Mercadoria fora da Embalagem de Atacadista
18	Mercadorias Trocadas
19	Reentrega Solicitada pelo Cliente
20	Entrega Prejudicada por Horário/Falta de Tempo Hábil
21	Estabelecimento Fechado
22	Reentrega sem Cobrança do Cliente
23	Extravio de Mercadoria em Trânsito
24	Mercadoria Reentregue ao Cliente Destino
25	Mercadoria Devolvida ao Cliente de Origem
26	Nota Fiscal Retida pela Fiscalização
27	Roubo de Carga
28	Mercadoria Retida até Segunda Ordem
29	Cliente Retira Mercadoria na Transportadora
30	Problema com a Documentação (Nota Fiscal e/ou CTRC)
31	Entrega com Indenização Efetuada
32	Falta com Solicitação de Reposição
33	Falta com Busca/Reconferência
34	Cliente Fechado para Balanço
35	Quantidade de Produto em Desacordo (Nota Fiscal e/ou Pedido)
36	Extravio de documentos pela cia. Aérea
37	Extravio de carga pela cia. Aérea
38	Avaria de carga pela cia. Aérea
39	Corte de carga na pista
40	Aeroporto fechado na origem
41	Pedido de Compra Incompleto
42	Nota Fiscal com Produtos de Setores Diferentes
43	Feriado Local/Nacional
44	Excesso de Veículos
45	Cliente Destino Encerrou Atividades
46	Responsável de Recebimento Ausente
47	Cliente Destino em Greve
48	Aeroporto fechado no destino
49	Vôo cancelado
50	Greve nacional (Greve Geral)
51	Mercadoria Vencida (Data de Validade Expirada)
52	Mercadoria Redespachada (Entregue para Redespacho)
53	Mercadoria não foi Embarcada
54	Mercadoria Embarcada sem Conhecimento/Conhecimento não Embarcado
55	Endereço de Transportadora de Redespacho não Localizado/Informado
56	Cliente não Aceita Mercadoria com Pagamento de Reembolso
57	Transportadora não Atende a Cidade da Transportadora de Redespacho
58	Quebra do Veiculo de Entrega
59	Cliente sem Verba para Pagar o Frete
60	Endereço de Entrega Errado
61	Cliente sem Verba para Reembolso
62	Recusa da Carga por Valor de Frete Errado
63	Identificação do Cliente não Informada/Enviada/Insuficiente
64	Cliente não Identificado/Cadastrado
65	Entrar em Contato com o Comprador
66	Troca não Disponível
67	Fins Estatísticos
68	Data de Entrega Diferente do Pedido
69	Substituição Tributária
70	Sistema Fora do Ar
71	Cliente Destino não Recebe Pedido Parcial
72	Cliente Destino só Recebe Pedido Parcial
73	Redespacho somente com Frete Pago
74	Funcionário não autorizado a Receber Mercadorias
75	Mercadoria Embarcada para Rota Indevida
76	Estrada/Entrada de Acesso Interditada
77	Cliente Destino Mudou de Endereço
78	Avaria Total
79	Avaria Parcial
80	Extravio Total
81	Extravio Parcial
82	Sobra de Mercadoria sem Nota Fiscal
83	Mercadoria em poder da SUFRAMA para Internação
84	Mercadoria Retirada para Conferência
85	Apreensão Fiscal da Mercadoria
86	Excesso de Carga/Peso
87	Férias Coletivas
88	Recusado, aguardando negociação
89	Aguardando refaturamento das mercadorias
90	Recusado pelo Redespachante
91	Entrega Programada
92	Problemas Fiscais
93	Aguardando carta de correção
94	Recusa por divergência nas condições de pagamento
95	Carga aguardando vôo conexão
96	Carga sem embalagem própria para transp. Aéreo
97	Carga com dimensão superior ao porão da aeronave
98	Chegada na cidade ou filial de destino
99	Outros tipos de ocorrências não especificados acima