Recursos da API
Nota Fiscal
Envie Notas Fiscais Eletrônicas (NF-e) em Base64 para a API Frete Barato.
O endpoint de Invoice foi desenvolvido para receber e processar Notas Fiscais Eletrônicas (NF-e) em formato Base64.
Esta API permite que sistemas externos enviem documentos fiscais XML codificados em Base64, garantindo integridade, segurança e rastreabilidade no processo de recebimento.
O sistema realiza validações rigorosas em todas as etapas do processo, desde a estrutura do payload até a validação do conteúdo do documento decodificado.
Endpoint
https://admin.fretebarato.com/invoice/push/v1/base64/{{customer_token}}
Envie uma nota fiscal (push)
curl -X POST "https://admin.fretebarato.com/invoice/push/v1/base64/{{customer_token}}" \
-H "Authorization: Bearer xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "User-Agent: MinhaAplicacao ([email protected])" \
-d '{
"request_id": "01HZQK3F2N8PYVJ9KQ6R4WXM5T",
"created_at": "2025-10-29T15:12:34Z",
"document_meta": {
"type": "nf-e",
"model": "55",
"nota_fiscal_id": "35150000000000000000000000000000000061234567"
},
"document_encoding": {
"format": "base64",
"mimetype": "application/xml"
},
"document_payload": {
"data": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4..."
}
}'
$url = "https://admin.fretebarato.com/invoice/push/v1/base64/{{customer_token}}";
$payload = array(
"request_id" => "01HZQK3F2N8PYVJ9KQ6R4WXM5T",
"created_at" => "2025-10-29T15:12:34Z",
"document_meta" => array(
"type" => "nf-e",
"model" => "55",
"nota_fiscal_id" => "35150000000000000000000000000000000061234567"
),
"document_encoding" => array(
"format" => "base64",
"mimetype" => "application/xml"
),
"document_payload" => array(
"data" => base64_encode($xmlContent)
)
);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$headers = array(
"Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type: application/json",
"User-Agent: MinhaAplicacao ([email protected])"
);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($payload));
$response = curl_exec($curl);
curl_close($curl);
{
"request_id": "01HZQK3F2N8PYVJ9KQ6R4WXM5T",
"created_at": "2025-10-29T15:12:34Z",
"document_meta": {
"type": "nf-e",
"model": "55",
"nota_fiscal_id": "35150000000000000000000000000000000061234567"
},
"document_encoding": {
"format": "base64",
"mimetype": "application/xml"
},
"document_payload": {
"data": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4..."
}
}
{
"success": true,
"message": "Invoice received successfully (Base64 format)",
"data": {
"request_id": "01HZQK3F2N8PYVJ9KQ6R4WXM5T",
"document_meta": {
"type": "nf-e",
"model": "55",
"nota_fiscal_id": "35150000000000000000000000000000000061234567"
},
"document_encoding": {
"format": "base64",
"mimetype": "application/xml"
},
"document_size": 15420,
"customer_code": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4",
"received_at": "2025-10-29 15:12:35",
"processed_at": "2025-10-29 15:12:35"
}
}
Headers
| Key | Value | Observação |
|---|---|---|
Authorization | Bearer {{token}} | Token de autenticação fornecido pela equipe Frete Barato |
Content-Type | application/json | Obrigatório para envio de payload JSON |
User-Agent | Aplicação (e-mail para contato técnico) | Opcional, mas recomendado para identificação |
Parâmetros do payload
Campos de primeiro nível
| Parâmetro | Tipo | Obrigatório | Observação |
|---|---|---|---|
request_id | String | Sim | Identificador único da requisição (UUID ou ULID). Deve ter entre 20 e 36 caracteres |
created_at | String | Sim | Data/hora de criação no formato ISO 8601 (ex: 2025-10-29T15:12:34Z) |
document_meta | Object | Sim | Objeto contendo metadados do documento fiscal |
document_encoding | Object | Sim | Objeto contendo informações de codificação do documento |
document_payload | Object | Sim | Objeto contendo o documento codificado em Base64 |
Campos do objeto document_meta
| Parâmetro | Tipo | Obrigatório | Observação |
|---|---|---|---|
type | String | Sim | Tipo do documento fiscal. Valores aceitos: nf-e (Nota Fiscal Eletrônica) |
model | String | Sim | Modelo do documento fiscal (ex: 55 para NF-e) |
nota_fiscal_id | String | Sim | Chave de acesso da NF-e. Deve conter exatamente 44 caracteres numéricos |
Campos do objeto document_encoding
| Parâmetro | Tipo | Obrigatório | Observação |
|---|---|---|---|
format | String | Sim | Formato de codificação. Atualmente aceito apenas: base64 |
mimetype | String | Sim | Tipo MIME do documento original. Valores aceitos: application/xml, text/xml |
Campos do objeto document_payload
| Parâmetro | Tipo | Obrigatório | Observação |
|---|---|---|---|
data | String | Sim | Documento fiscal codificado em Base64. Após decodificação, deve ter no mínimo 100 bytes |
Parâmetros do response
| Parâmetro | Tipo | Comportamento |
|---|---|---|
success | Boolean | Indica se a requisição foi processada com sucesso (true/false) |
message | String | Mensagem descritiva sobre o resultado do processamento |
data | Object | Objeto contendo detalhes do documento processado (presente apenas em caso de sucesso) |
data.request_id | String | Retorna o identificador único da requisição enviada |
data.document_meta | Object | Retorna os metadados do documento processado |
data.document_encoding | Object | Retorna as informações de codificação do documento |
data.document_size | Numeric | Retorna o tamanho do documento decodificado em bytes |
data.customer_code | String | Retorna o código identificador do cliente solicitante |
data.received_at | String | Data/hora de recebimento do documento no formato Y-m-d H:i:s |
data.processed_at | String | Data/hora de processamento do documento no formato Y-m-d H:i:s |
Conheça as validações realizadas
A API realiza validações rigorosas em múltiplas camadas:
| Tipo de validação | Descrição | Erro retornado |
|---|---|---|
| Autenticação | Valida Bearer Token no header Authorization | 401 - Authentication failure |
| Dispatcher | Valida versão da API (v1) e formato (base64) | 401 - Authentication failure / Only base64 format is supported |
| Token cliente | Valida se o token do cliente possui 32 caracteres | 401 - Authentication failure |
| Cliente existente | Verifica se o cliente existe na base de dados | 404 - Customer not found |
| Estrutura JSON | Valida se todos os campos obrigatórios estão presentes | 400 - Field campo is required |
| Request ID | Valida se é um UUID/ULID válido (20-36 caracteres) | 400 - Field request_id must be a valid UUID or ULID |
| Data ISO 8601 | Valida formato de data created_at | 400 - Field created_at must be a valid ISO 8601 datetime |
| Tipo documento | Valida se o tipo é nf-e | 400 - Field document_meta.type must be one of: nf-e |
| Formato encoding | Valida se o formato é base64 | 400 - Field document_encoding.format must be "base64" |
| Mimetype | Valida se é application/xml ou text/xml | 400 - Field document_encoding.mimetype must be one of: ... |
| Chave NF-e | Valida se possui exatamente 44 caracteres numéricos | 400 - Field document_meta.nota_fiscal_id must be exactly 44 characters |
| Base64 válido | Valida se o Base64 pode ser decodificado | 400 - Invalid base64 document format |
| Documento vazio | Valida se documento decodificado não está vazio | 400 - Decoded document is empty |
| Tamanho mínimo | Valida se documento decodificado possui mínimo 100 bytes | 400 - Decoded document is too small (minimum 100 bytes) |
| Conteúdo vs mimetype | Valida se conteúdo corresponde ao mimetype declarado | 400 - Document content does not match declared mimetype |
Trate os erros
| Response | Tipo | Mensagem | Descrição |
|---|---|---|---|
200 | success | Invoice received successfully (Base64 format) | Nota fiscal recebida e processada com sucesso |
400 | bad request | Field campo is required / Invalid params | Parâmetros ausentes, inválidos ou fora do padrão esperado |
401 | unauthorized | Authentication failure | Falha na autenticação: token inválido ou versão incorreta da API |
403 | forbidden | Access denied | Acesso negado ao recurso solicitado |
404 | not found | Customer not found | Cliente não encontrado na base de dados |
406 | not acceptable | Invalid Params (JSON) | Estrutura JSON inválida ou malformada |
500 | internal server error | Internal error | Erro interno do servidor durante o processamento |
Exemplos de erro
{
"message": "Field [request_id] is required",
"code": 400
}
{
"message": "Field [document_meta.nota_fiscal_id] must be exactly 44 characters",
"code": 400
}
{
"message": "Invalid base64 document format in [document_payload.data]",
"code": 400
}
{
"message": "Document content does not match declared mimetype (XML expected)",
"code": 400
}
{
"message": "Authentication failure",
"code": 401
}
{
"message": "Customer not found",
"code": 404
}
{
"message": "Invalid Params (JSON)",
"code": 406
}
{
"message": "Internal error",
"code": 500
}
Siga as boas práticas
- Request ID único — Sempre gere um identificador único (UUID v4 ou ULID) para cada requisição. Isso facilita rastreamento e debug.
- Timestamp preciso — Utilize formato ISO 8601 com timezone (ex:
2025-10-29T15:12:34Z) para garantir precisão temporal. - Validação prévia — Valide a estrutura do XML antes de codificar em Base64 para evitar erros desnecessários.
- Chave de acesso — Certifique-se de que a chave de 44 caracteres corresponde exatamente à chave presente no XML da NF-e.
- Mimetype correto — Declare o mimetype correto (
application/xmloutext/xml). - Tratamento de erros — Implemente lógica de retentativa para erros temporários (
500) e tratamento adequado para erros de validação (400). - Logs e auditoria — Mantenha logs detalhados das requisições usando o
request_idcomo chave de rastreamento. - Segurança — Nunca exponha o Bearer Token em logs ou sistemas de monitoramento.
Entenda o fluxo de processamento
Recepção
A API recebe o payload JSON com o documento em Base64.
Autenticação
Valida o Bearer Token e as credenciais do cliente.
Validação estrutural
Verifica todos os campos obrigatórios e seus formatos.
Decodificação
Decodifica o documento Base64 para o formato original.
Validação de conteúdo
Verifica se o conteúdo corresponde ao mimetype declarado.
Processamento
Executa as regras de negócio e a persistência dos dados.
Resposta
Retorna um JSON com o resultado do processamento.

