emites-client-api-docs

emites-client-api-docs [Português-BR]

Public documentation for the Emites-Client product API.

Introduction

Emites-Client is a Nexaas solution for issuing electronic invoices (NF-e) and consumer electronic invoices (NFC-e) developed in Java language. These documents can be issue in online or offline mode.

Integration with the application is accomplished by sending messages to a TCP/IP socket interface.

Protocol

All messages exchanged by the Emites-Client must follow the following text format:

Size:Identifier:Payload

where:

• Size: Numeric string representing the size of the data that follows it, also considering the separators (‘:’). Do not use zeros to the left;
• Identifier: string that identifies the type of message;
• Payload: string containing the payload in JSON format.

For example if we consider the following message:

27:TESTE:{ "teste": "teste" }

then we have:

• 27 is the size of the message data: 1 (”:”) + 5 (“TESTE”) + 1 (”:”) + 20 (JSON length);
• “TESTE” is the type of message being sent;
• after the last separator we have the JSON test payload.

Comments:

• The message should use encoding US-ASCII or ISO-8859-1 (or variations). Multibyte encodings such as UTF-8 should not be used;
• When sending a message to Emites-Client, wait for the corresponding response before sending a new request;
• The JSON payload can be sent on a single line or may contain line breaks, provided that the size of the breaks are considered in the total size of the message;
• To indicate an optional value missing from the JSON payload, simply omit the field; alternatively, it can be serialized with null value. Avoid sending missing values as empty strings (“”), because Emites-Client performs minimum size validation if the field is not null;

Creating a NFC-e

To create a NFC-e, send a message with the identifier CREATE_NFCE. In the response, it’s possible that the identifier be CREATE_NFCE or CREATE_CFE (in cases where the issue was made by SAT or MFE)..

Use as reference the following documents:

• JSON request YAML schema;
• JSON response YAML schema;
• Sample JSON request;
• Sample JSON response;

The response will contain the same fields that were sent in the request, and additionally the following exclusive fields:

• status with value equal to sucesso;
• Taxes (field produto.tributacao, for each product);
• Note’s number (field numero);
• Note’s serie (field serie);
• DANFE URL (field danfe_url);
• XML URL (field xml_url);
• Base64 encoded DANFE (field danfe);
• Base64 encoded XML (field xml);
• Issue response (field resposta_emissao, which contains the access key and protocol number);

Rejection

The rejected response will contain the same fields that were sent in the request, and additionally the following exclusive fields:

• status with value equal to rejeitada;
• erros with the list of rejection reasons;

The following excerpt shows an example of rejection due to validation errors:

{
  "status": "rejeitada",
  ...
  ...
  ...
  "erros": {
    "forma_de_pagamento": ["tamanho deve estar entre 1 e 100"],
    "cliente.email": ["não é um endereço de e-mail válido"]
  }
}

The following excerpt shows an example of rejection raised by SEFAZ:

{
  "status": "rejeitada",
  ...
  ...
  ...
  "erros": {
    "rejeicao": ["471 - Rejeição: Informado NCM=00 indevidamente"]
  }
}

NFC-e cancellation

To cancel an NFC-e, send a message with the identifier CANCEL_NFCE. The same identifier will be returned in the response.

The JSON payload should follow the format:

{ "chave_acesso": "53180922769530000131651110000001281355486170", "motivo": "Desistencia do comprador" }

where:

• chave_acesso is the NFC-e’s access key (obtained in the creation response);
• reason is the description of the reason for the cancellation (optional; if informed should be between 15 and 255 characters in size)

The cancellation response’s JSON payload will be similar to the one returned during the creation operation, with the following differences [(see example)] (/emites-client-api-docs/nfce/examples/nfce_cancel_response.json):

• status field will have the value cancelada;
• an additional cancel_xml_url field with the updated document’s URL will be included;
• an additional field resposta_cancelamento (which contains the new access key and new protocol number) will be included;

Rejection

As of 10/1/2018 the maximum period to cancel a NFC-e will be 30 minutes, according to the text of the Ajuste SINIEF 07/2018. After this period elapses, an attempt to cancel the document will be answered by SEFAZ with a rejection code (501).

If this scenario occurs, the response returned by the Emites-Client will contain the field errors informing the reason for the rejection:

{
  "status": "cancelamento_rejeitado",
  ...
  ...
  ...
  "erros": {
    "rejeicao": ["501 - Rejeicao: Prazo de Cancelamento Superior ao Previsto na Legislacao"]
  }
}

Creating a NF-e

To create a NF-e, send a message with the identifier CREATE_NFE. The same identifier will be returned in the response.

Use as reference the following documents:

• JSON request YAML schema;
• JSON devolution request YAML schema;
• JSON response YAML schema;
• Sample JSON request;
• Sample JSON devolution request;
• Sample JSON response;

The response will contain the same fields that were sent in the request, and additionally the following exclusive fields:

• status with value equal to sucesso;
• Taxes (field produto.tributacao, for each product);
• Note’s number (field numero);
• Note’s serie (field serie);
• DANFE URL (field danfe_url);
• XML URL (field xml_url);
• Base64 encoded DANFE (field danfe);
• Base64 encoded XML (field xml);
• Issue response (field resposta_emissao, which contains the access key and protocol number);

Only available for NFE

fields:

• engine_de_calculo
• contingencia

objects:

• nfe
• dados_gerais
• retencao_tributos
• cobranca

Note: The dados_gerais fields in NFE are in the root of NFCE with the same name

NF-e cancellation

To cancel an NF-e, send a message with the identifier CANCEL_NFE. The same identifier will be returned in the response.

The JSON payload should follow the format:

{ "chave_acesso": "53180922769530000131651110000001281355486170", "motivo": "Desistencia do comprador" }

where:

• chave_acesso is the NFC-e’s access key (obtained in the creation response);
• reason is the description of the reason for the cancellation (optional; if informed should be between 15 and 255 characters in size)

The cancellation response’s JSON payload will be similar to the one returned during the cancellation NFC-e operation.

Tax calculation

To calculate the taxes for an NFC-e (Electronic Consumer Invoice), send a message with the identifier CALCULATE. The same identifier will be returned in response.

Use as reference the documents used to create an NFCE-e by the Emites Client.

Useful links

• JSON schema: Documentation of vocabulary used for JSON schemas;
• JSON schema validator: allows you to validate a JSON string against its schema;

This site is open source. Improve this page.