Tera · Documentação da API

Início

Através desta API é possível enviar QR Codes de notas fiscais para processamento e recuperar o JSON da nota fiscal.

Resposta padrão de Erro

Todos os erros enviados por esta API terão um json com a estrutura a seguir, podendo variar o status code da resposta a depender do endpoint e do erro.

{

"message"

string

Uma mensagem de erro amigável para humanos, ideal para dar feedback ao usuário

"errorCode"

string

Um código de erro amigável para robôs, ideal para implementar regras de controle com IF, SWITCH e etc

}

Tabela de referência de Error Code

Error codes diferentes podem ser enviados por endpoints específicos. Estes Error Codes são os padrões que podem ser enviados por qualquer endpoints.

Error Code	Status Code	Descrição
VALIDATION_ERROR	400	Algum campo obrigatório não foi enviado ou um valor inválido foi enviado na requisição. A invalidez do conteúdo da nota (ex: nota sem valor, data de emissão inconsistente) não usa este código: é sinalizada pelo status INVALID.
AUTHENTICATION_ERROR	401	O token de autenticação não foi enviado, está expirado ou é inválido
SERVER_ERROR	500	Um erro interno ocorreu na API e nosso time de desenvolvedores trabalhará na correção o mais rápido possível
DENIED_ERROR	403	Uso abusivo da API foi identificado e a requisição foi recusada

Autenticação

Para autenticar-se na API é necessário enviar um API TOKEN.

Endpoints com o marcador Público não precisam do envio do API TOKEN.

O API TOKEN é enviado através do header Authorization como no exemplo:

Authorization: Bearer MS4yMzUgMTI2ZTUgMjFlNjIxNSBlMTEyIDFlMTJlMTYxNTJlMSA2MTEyZTExMjY1ZTExMg==

O API TOKEN pode ser gerado no Portal do Cliente e terá a duração padrão de 1 ano.

É possível automatizar a renovação do API TOKEN através da API.

Resposta de Token não Enviado

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{

"message"

string

"Autenticação necessária"

"errorCode"

string

"AUTHENTICATION_ERROR"

}

Resposta de Token inválido ou expirado

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{

"message"

string

"Sessão encerrada, por favor acesse novamente"

"errorCode"

string

"AUTHENTICATION_ERROR"

}

Notas

Endpoints para envio e recebimento de notas.

Enviar URLs de QR Code

Uma Nota Fiscal possui um QR Code que possui uma url para sua visualização no site da Receita Federal.

O envio de uma nota fiscal para processamento na API é feito através do envio do conteúdo deste QR Code.

Este endpoint permite enviar URLs em lotes respeitando o limite de 100 URLs por requisição.

Uma vez enviadas, a API retorna, para cada URL/chave, o status do envio (sucesso ou erro) e a chave de acesso (accessKey) correspondente. Guarde a accessKey: a consulta dos dados é feita posteriormente, nota a nota, via Consultar Nota, autenticando com o seu bearer token.

No lugar da URL, pode ser enviada apenas a chave de acesso de 44 dígitos

POST

https://api.terabr.com/v1/receipt/qr-code

Copiar

Corpo da Requisição

{

"qrCodes"

: [

{

"url"

URL do QR Code da nota ou a chave de acesso de 44 dígitos

"importDelayMinutes"

Tempo de adiamento da importação da nota em minutos, por chave de acesso

"expirationHours"

Tempo limite para importar a nota em horas, por chave de acesso

"meta"

: {

Objeto opcional para uso do cliente, ao recuperar a nota, o mesmo objeto enviado aqui estará presente.

Este objeto tem um limite de 5 campos.

}

"importDelayMinutes"

Tempo de adiamento da importação da nota em minutos

Padrão: 0

"expirationHours"

Tempo limite para importar a nota em horas

Padrão: 120

"reprocess"

true ou false

Padrão: false

Processa a nota novamente caso seja true

}

Resposta de Sucesso

HTTP/1.1 200 OK
Content-Type: application/json

{

"result"

: [

{

"url"

string

URL do QR Code enviada

"status"

RECEIVED

INVALID

ERROR

DUPLICATED

"message"

string

Opcional, mensagem de erro caso a URL seja inválida

"accessKey"

string

Chave de acesso de 44 dígitos

"uf"

string

Código IBGE da UF emissora, ex: 33, 29

"ufInitials"

string

Sigla da UF, ex: RJ, BA

"year"

number

Ano de emissão

"month"

number

Mês de emissão

"cnpj"

string

CNPJ do emissor

"model"

string

Código do modelo: 59 SAT, 65 NFC-e, 55 DANFE

"series"

string

"number"

string

"token"

string

"dv"

string

Dígito verificador

}

]

}

Os campos da chave (accessKey, uf, cnpj, model e os demais) vêm preenchidos quando a nota é identificada a partir da URL. Em URLs inválidas, retornam apenas url, status e message. O campo accessKey também é retornado como accesskey (minúsculo) por compatibilidade.

Tabela de Referência dos Status

Status	Descrição
RECEIVED	A nota foi recebida e será processada
INVALID	A url está inválida pelo motivo descrito na mensagem, como por exemplo: Não conter uma chave de acesso de 44 dígitos válida
ERROR	Houve algum erro interno da API ao receber essa nota, neste caso é aconselhável tentar novamente em alguns instantes.
DUPLICATED	A nota já foi enviada e a configuração de reprocesso não foi ativada

Validar Chave de Acesso

Valida uma chave de acesso de 44 dígitos e retorna seus dados decompostos (UF, modelo, emissor e demais) sem enviar a nota para processamento. Útil para conferir a chave antes do envio.

Este endpoint não tem cobrança e não recupera o conteúdo da nota: apenas decompõe e valida a chave informada.

GET

https://api.terabr.com/v1/receipt/[CHAVE_DE_ACESSO_DA_NOTA_FISCAL]/validate

Copiar

Resposta de Sucesso (chave válida)

HTTP/1.1 200 OK
Content-Type: application/json

{

"result"

"accessKey"

string

Chave de acesso de 44 dígitos

"uf"

string

Código IBGE da UF emissora, ex: 33, 29

"ufInitials"

string

Sigla da UF, ex: RJ, BA

"year"

number

Ano de emissão

"month"

number

Mês de emissão

"cnpj"

string

CNPJ do emissor

"model"

string

Código do modelo: 59 SAT, 65 NFC-e, 55 DANFE

"series"

string

"number"

string

"token"

string

"dv"

string

Dígito verificador

}

Resposta de Chave Inválida

HTTP/1.1 200 OK
Content-Type: application/json

{

"result"

INVALID

"reason"

string

Motivo da invalidez

"reasonCodes"

string[]

Códigos do motivo

}

Consultar Nota

Recupera o Status de uma Nota Fiscal que teve sua url previamente enviada.

GET

https://api.terabr.com/v1/receipt/[CHAVE_DE_ACESSO_DA_NOTA_FISCAL]

Copiar

Resposta de Sucesso

HTTP/1.1 200 OK
Content-Type: application/json

{

"status"

RECEIVED

INVALID

ERROR

"message"

string

Mensagem do erro de validação caso exista

"meta"

: {

O objeto passado ao enviar a nota, caso exista.

"receipt"

: {

Campo presente caso status seja OK

"uf"

string

Código do IBGE da UF emissora da nota, ex: 33, 29, ...

"ufInitials"

string

Sigla da UF emissora da nota, ex: RJ, BA, ...

"year"

number

Ano de emissão da nota

"month"

number

Mês de emissão da nota

"cnpj"

string

CNPJ do emissor da nota

"model"

string

Código do modelo da nota, 59 para SAT, 65 para NFCE e 55 para DANFE

"series"

string

"number"

string

"token"

string

"dv"

string

"accessKey"

string

Chave de acesso de 44 dígitos da nota

"shopperDocument"

string

CNPJ ou CPF do comprador

"shopperAddress"

string

"shopperNeighborhood"

string

"shopperCep"

string

"shopperCity"

string

"shopperTelephone"

string

"shopperState"

string

"shopperCountry"

string

"companyTradeName"

string

Nome fantasia do emissor da nota

"companyName"

string

Razão social do emissor da nota

"companyAddress"

string

"companyNeighborhood"

string

"companyCep"

string

"companyCity"

string

"companyTelephone"

string

"discountValue"

number

"totalValue"

number

Valor final da nota com aplicação dos descontos

"emissionDt"

string

Formato: yyyy-mm-dd HH:mm

"stateRegistration"

string

"cityRegistration"

string

"paymentMethods"

: [

{

"indicator"

string

"description"

string

"value"

number

"paymentIntegrationType"

string

"accreditorCnpj"

string

"operatorBrand"

string

"authorizationNumber"

string

}

"items"

: [

{

"description"

string

Descrição do produto no Lojista

"code"

string

Código do Produto no Lojista

"amount"

number

Quantidade vendida

"unity"

string

"unitaryValue"

number

"value"

number

Valor total

"isOnPromotion"

boolean

Produto faz parte da lista promocional

"customerProductName"

string

Nome do produto conforme cadastro do cliente

"customerProductShortName"

string

Nome abreviado do produto conforme cadastro do cliente

"customerBrand"

string

Marca do produto conforme cadastro do cliente

"customerManufacturer"

string

Fabricante do produto conforme cadastro do cliente

"customerCategory1"

string

Categoria nível 1 do produto conforme cadastro do cliente

"customerCategory2"

string

Categoria nível 2 do produto conforme cadastro do cliente

"customerCategory3"

string

Categoria nível 3 do produto conforme cadastro do cliente

"customerCategory4"

string

Categoria nível 4 do produto conforme cadastro do cliente

"customerCategory5"

string

Categoria nível 5 do produto conforme cadastro do cliente

"customerQty"

number

Quantidade do produto conforme cadastro do cliente

"customerPackQty"

number

Quantidade de unidades por embalagem conforme cadastro do cliente

"ncm"

string

"cfop"

string

"cest"

string

"discountValue"

number

"identifiedEan"

string

Ean identificado pela Tera

"identifiedNcm"

string

Ncm identificado pela Tera

"commercialEan"

string

Ean informado pelo Lojista

"commercialUnity"

string

"commercialAmount"

number

"commercialUnitaryValue"

number

"taxableEan"

string

Ean informado pelo Lojista

"taxableUnity"

string

"taxableAmount"

number

"taxableUnitaryValue"

number

"approximateValueOfTaxes"

number

}

]

}

Tabela de Referência dos Status

Status	Descrição
OK	A nota foi recebida e processada com sucesso
NOT_FOUND	Esta chave de acesso não foi enviada para processamento
RECEIVED	A nota foi recebida e ainda está em processamento
INVALID	Foi identificado que a nota recebida é inválida ou não existe
ERROR	Houve algum erro interno da API ao recuperar essa nota, neste caso é aconselhável tentar novamente em alguns instantes.

Parâmetros

Campo	Obrigatório	Descrição
filterProducts	Não	Os itens de seu interesse, informados previamente, serão filtrados e retornados pela API. Recomendamos validar os resultados caso não retorne os itens desejados.

Exemplo de uso do filterProducts

O filterProducts é enviado como parâmetro de query na chamada de Consultar Nota. Com 1, a API retorna apenas os itens cujos produtos foram previamente cadastrados no seu projeto (identificados por EAN); com 0 (padrão), retorna todos os itens da nota.

GET https://api.terabr.com/v1/receipt/[CHAVE_DE_ACESSO_DA_NOTA_FISCAL]?filterProducts=1

Consultar Notas

Consulta Notas Fiscais enviadas previamente em lotes.

Este endpoint não possui cobrança mas também não entrega o json da nota, apenas seu status.

POST

https://api.terabr.com/v1/receipt/search

Copiar

Corpo da Requisição

{

"accessKeys"

: [

Chaves de Acesso de Nota Fiscal

]

}

Resposta de Sucesso

HTTP/1.1 200 OK
Content-Type: application/json

{

"accessKeys"

: [

{

"accessKey"

string

Chave de Acesso

"status"

RECEIVED

INVALID

ERROR

"message"

string

Mensagem do erro de validação caso exista

}

]

}

Webhooks

Através do webhook, é possível receber a informação de quando há mudança de status numa nota sem a necessidade de fazer várias requisições periódicas para busca-la.

Essa abordagem reduz gastos com transferência de rede e trás melhor escalabilidade.

Um webhook é um endpoint em uma api servida pelo cliente, que caso o cliente registre em nossa plataforma, faremos requisições para este endpoint sempre que ocorrer algum evento.

É possível cadastrar webhooks no Portal do Cliente ou através da API. Entretanto só é possível ter um webhook por projeto, na API salvar a configuração de um webhook sempre sobrescreve a configuração atual caso exista.

Segurança

Para que o cliente tenha a garantia de que realmente somos nós quem estamos fazendo a requisição do Webhook, é possível configurar um token que enviaremos via Header no seguinte formato:

Authorization: Bearer

Token Configurado

Estrutura Padrão da Requisição

A requisição que faremos ao endpoint do webhook será um POST com corpo em json. No corpo terá um campo com o tipo de evento ocorrido e outro campo com dados sobre ele.

A estrutura do objeto com os dados do evento pode variar em função do tipo de evento.

POST

Path da sua URL

HTTP/1.1

Host:

Host da sua URL

Authorization: Bearer

Token Configurado

Content-Type: application/json

{

"eventType"

string

Tipo de Evento

"eventData"

object

Objeto com dados sobre o evento

}

Retentativas e Tratamento de Erros

Ao chamar o webhook iremos esperar que o retorno seja um status da família 2xx. Caso o contrário iremos entender que sua API teve problemas para processar a requisição e faremos retentativas a cada 1 hora durante três dias. Após este prazo caso não tenhamos uma resposta 2xx, iremos desistir de notificar o evento.

Qualquer conteúdo enviado no corpo da resposta será ignorado.

Tipos de Eventos do Webhook

Breve resumo sobre todos os tipos de eventos enviados no webhook. Falaremos sobre cada evento em maiores detalhes em sessões posteriores.

Tipo de Evento	Descrição
RECEIPT_STATUS_UPDATED	Uma nota enviada previamente na API mudou de status

Evento de Nota Atualizada

Sempre que uma nota fiscal mudar de status, faremos uma chamada ao webhook como evento RECEIPT_STATUS_UPDATED para notificar esta mudança.

Caso o status seja OK, é necessário usar o endpoint de Consultar Nota para recuperar o json da nota, o webhook não irá mandar o json da nota.

{

"accessKey"

string

Chave de Acesso de 44 dígitos

"status"

object

Status atual da nota, consultar tabela de referência do endpoint de consulta de notas

}