Upload
jorgecarvalho
View
184
Download
27
Embed Size (px)
Citation preview
2
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
ÍNDICE
1. INTRODUÇÃO .............................................................................................................................................. 6
2. MÓDULO NFSE (SERVIÇO) ......................................................................................................................... 6
2.1. OBSERVAÇÕES GERAIS ........................................................................................................................... 6 2.2. MÉTODO: POST ........................................................................................................................................ 6 2.2.1. ENVIARPACOTE ..................................................................................................................................................... 6
2.2.2. CANCELAR ............................................................................................................................................................ 8
2.2.3. MARCARCONSULTADO: ....................................................................................................................................... 10
2.2.4. CONSULTARRPSSAGUARDANDODOWNLOAD: ....................................................................................................... 11
2.2.5. UPLOADRETORNOPREFEITURA: ........................................................................................................................... 13
2.2.6. CONVERTIDA: ...................................................................................................................................................... 15
2.3. MÉTODO: GET ........................................................................................................................................ 17 2.3.1. CONSULTA PADRÃO ............................................................................................................................................ 17
3. MÓDULO NFE (MERCANTIL) .................................................................................................................... 19
3.1. OBSERVAÇÕES GERAIS .......................................................................................................................... 19 3.2. MÉTODO: POST ...................................................................................................................................... 19 3.2.1. ENVIARPACOTE: .................................................................................................................................................. 19
3.2.2. CANCELAR .......................................................................................................................................................... 21
3.2.3. INUTILIZAR .......................................................................................................................................................... 23
3.2.4. ENVIARCARTACORRECAONFE .............................................................................................................................. 24
3.2.5. MARCARCONSULTADO ........................................................................................................................................ 26
3.2.6. MARCARIMPRESSO .............................................................................................................................................. 28
3.2.7. MARCARCARTACORRECAOIMPRESSO ................................................................................................................... 29
3.2.8. REIMPRESSAODANFE .......................................................................................................................................... 31
3.2.9. CONSULTAR CADASTRO ....................................................................................................................................... 33
3.3. MÉTODO: GET ........................................................................................................................................ 35 3.3.1. CONSULTA PADRÃO:............................................................................................................................................ 35
3.3.2. GETXML .............................................................................................................................................................. 38
3.3.3. GETXMLCANCELAMENTO ..................................................................................................................................... 39
3.3.4. GETDANFE .......................................................................................................................................................... 40
3.3.5. GETSTATUS ......................................................................................................................................................... 42
3.3.6. GETSTATUS (COM PARÂMETROS) .......................................................................................................................... 43
3.3.7. CONSULTA RETORNO: ......................................................................................................................................... 45
3
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
3.3.8. CONSULTA IMPRESSÃO: ....................................................................................................................................... 47
3.3.9. CONSULTA IMPRESSÃO NFE: ................................................................................................................................ 49
3.3.10. CONSULTA IMPRESSÃO CARTA CORREÇÃO NFE: ................................................................................................... 50
4. MÓDULO CTE ............................................................................................................................................ 52
4.1. OBSERVAÇÕES GERAIS ......................................................................................................................... 52 4.2. MÉTODO: POST ...................................................................................................................................... 52 4.2.1. ENVIARPACOTE: .................................................................................................................................................. 53
4.2.2. CANCELAR .......................................................................................................................................................... 54
4.2.3. ENVIARCARTACORRECAOCTE .............................................................................................................................. 56
4.2.4. INUTILIZAR .......................................................................................................................................................... 57
4.2.5. MARCARCONSULTADO ........................................................................................................................................ 59
4.2.6. MARCARIMPRESSO .............................................................................................................................................. 61
4.2.7. MARCARCARTACORRECAOIMPRESSO ................................................................................................................... 62
4.3. MÉTODO: GET ........................................................................................................................................ 64 4.3.1. CONSULTA PADRÃO ............................................................................................................................................ 64
4.3.2. GETXML .............................................................................................................................................................. 66
4.3.3. GETXMLCANCELAMENTO ..................................................................................................................................... 68
4.3.4. GETDACTE .......................................................................................................................................................... 69
4.3.5. GETSTATUS ......................................................................................................................................................... 70
4.3.6. CONSULTA RETORNO .......................................................................................................................................... 72
4.3.7. CONSULTA IMPRESSÃO ........................................................................................................................................ 74
5. MÓDULO MDFE ......................................................................................................................................... 75
5.1. OBSERVAÇÕES GERAIS ......................................................................................................................... 75 5.2. MÉTODO: POST ...................................................................................................................................... 76 5.2.1. ENVIARPACOTE: .................................................................................................................................................. 76
5.2.2. CANCELAR .......................................................................................................................................................... 77
5.2.3. ENCERRAR .......................................................................................................................................................... 79
5.2.4. MARCARCONSULTADO ........................................................................................................................................ 81
5.2.5. MARCARIMPRESSO .............................................................................................................................................. 82
5.3. MÉTODO: GET ........................................................................................................................................ 84 5.3.1. CONSULTA PADRÃO ............................................................................................................................................ 84
5.3.2. GETXML .............................................................................................................................................................. 86
5.3.3. CONSULTA RETORNO .......................................................................................................................................... 87
5.3.4. CONSULTA IMPRESSÃO ........................................................................................................................................ 89
5.3.5. GETDAMDFE ....................................................................................................................................................... 91
4
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
6. MÓDULO RECEPTOR NFSE (SERVIÇO) .................................................................................................... 92
6.1. OBSERVAÇÕES GERAIS ......................................................................................................................... 92 6.2. MÉTODO: POST ........................................................................................................................................ 92 6.2.1. MARCARCONSULTADO: ....................................................................................................................................... 92
6.3. MÉTODO: GET ........................................................................................................................................ 94 6.3.1. CONSULTA PADRÃO ............................................................................................................................................ 94
7. MÓDULO RECEPTOR NFE (MERCANTIL) ................................................................................................. 95
7.1. OBSERVAÇÕES GERAIS .......................................................................................................................... 95 7.2. MÉTODO: POST ...................................................................................................................................... 96 7.2.1. ENVIARRECEBIMENTO .......................................................................................................................................... 96
7.2.2. ENVIAREVENTOMANIFESTACAO ........................................................................................................................... 98
7.2.3. MARCARCONSULTADO: ..................................................................................................................................... 100
7.2.4. MARCARIMPRESSO: ........................................................................................................................................... 101
7.3. MÉTODO: GET....................................................................................................................................... 103 7.3.1. CONSULTA PADRÃO .......................................................................................................................................... 103
7.3.2. GETXML ............................................................................................................................................................ 104
7.3.3. GETXMLCANCELAMENTO ................................................................................................................................... 106
7.3.4. GETSTATUS ....................................................................................................................................................... 107
7.3.5. CONSULTA IMPRESSÃO ...................................................................................................................................... 109
8. MÓDULO RECEPTOR CTE ....................................................................................................................... 110
8.1. OBSERVAÇÕES GERAIS ....................................................................................................................... 110 8.2. MÉTODO: POST .................................................................................................................................... 110 8.2.1. ENVIARRECEBIMENTO ........................................................................................................................................ 110
8.2.2. CONSULTARDOCFORNECEDOR .......................................................................................................................... 112
8.2.3. RESGATARXMLFORNECEDOR ............................................................................................................................. 115
8.2.4. MARCARCONSULTADO: ..................................................................................................................................... 117
8.3. MÉTODO: GET ...................................................................................................................................... 119 8.3.1. CONSULTA PADRÃO .......................................................................................................................................... 119
8.3.2. GETXML ............................................................................................................................................................ 120
8.3.3. GETXMLCANCELAMENTO ................................................................................................................................... 122
8.3.4. GETSTATUS ....................................................................................................................................................... 123
9. LISTAGEM DE ERROS ............................................................................................................................. 125
10. EXEMPLO DE COMO UTILIZAR O WEBSERVICE .................................................................................. 125
10.1. OBSERVAÇÕES GERAIS ...................................................................................................................... 125 10.2. UTILIZANDO A EXTENSÃO REST CLIENT DO FIREFOX ..................................................................... 126
5
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
10.2.1. COMO INFORMAR OS DADOS? ............................................................................................................................. 126
10.2.2. EXEMPLO DE POST ........................................................................................................................................... 128
10.2.3. EXEMPLO DE GET .............................................................................................................................................. 129
11. PROGRAMA EXEMPLO EM JAVA ........................................................................................................... 129
12. RELAÇÃO DE MUDANÇAS DE VERSÕES DO MANUAL ........................................................................ 130
13. SUPORTE TÉCNICO ............................................................................................................................... 132
6
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
1. INTRODUÇÃO
O módulo Webservice da Solução MASTERSAF DFE V3 é baseado em requisições REST. Utilizamos dois
tipos de requisições: POST e GET. Todas as requisições exigem um usuário e senha informados por Basic
Authentication.
As requisições do tipo POST exigem algum conteúdo (Request Body). É através desse conteúdo que a
requisição será processada.
Nas requisições do tipo GET não é necessário informar nenhum conteúdo, pois na própria URL serão
passados os parâmetros.
2. MÓDULO NFSE (SERVIÇO)
2.1. OBSERVAÇÕES GERAIS
Resumindo o processo, primeiramente é enviado um pacote de dados; depois é feita uma consulta
recebendo uma lista de ids e, então por fim, marcam-se no sistema os ids consultados para que numa
próxima consulta eles não sejam retornados novamente.
Com isso basta realizar POST para enviar os pacotes e GET para consultar o resultado do
processamento.
2.2. MÉTODO: POST
2.2.1. EnviarPacote
2.2.1.1. Introdução
Método utilizado para enviar RPSs ao WebService.
2.2.1.2. URL:
<host>:<port>/<webservice>/api/dfe
7
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
2.2.1.3. Exemplo URL:
http://localhost:8080/webservice/api/dfe (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/dfe (ambiente de homologação do SaaS)
2.2.1.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG
action Ação solicitada EnviarPacote Sim
txt_conteudo Conteúdo do RPS. Informar dados do RPS
conforme layout padrão do produto. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
2.2.1.5. Permissões
Permissões conforme cadastro de usuários:
- NFS-e Integrador (ROLE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
2.2.1.6. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- -
2.2.1.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "txt_conteudo".
O separador de campos do conteúdo é o pipe ( | ). Para quebra de linha usa-se \n.
8
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Para enviar vários RPSs você deve concatenar as strings antes de colocar em txt_conteúdo (txt conteúdo
terá vários "__rps__|versao=1(...)"), mas só pode existir um "__arquivo_fim__|". No caso de cancelamento o
procedimento é o mesmo (vários __cancelamento__ e apenas um __arquivo_fim__|).
Exemplo de Request Body conforme arquivo de exemplo: nfse_request_post_enviar_pacote.txt
2.2.1.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 202
2.2.1.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 400, 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
2.2.2. Cancelar
2.2.2.1. Introdução
Método para cancelar RPSs enviados ao webservice.
2.2.2.2. URL:
<host>:<port>/<webservice>/api/dfe
2.2.2.3. Exemplo URL:
http://localhost:8080/webservice/api/dfe (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/dfe (ambiente de homologação do SaaS)
2.2.2.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG.
action Ação solicitada Cancelar Sim
9
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
txt_conteudo Conteúdo do Cancelamento de RPS. Informar dados do
RPS conforme layout padrão do produto. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
2.2.2.5. Permissões
Permissões conforme cadastro de usuários:
- NFS-e Integrador (ROLE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
2.2.2.6. Cabeçalho
Detalhes que devem ser informados na requisição:
- authentication utilizando o usuário e
a senha fornecidos.
- -
2.2.2.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "txt_conteudo".
O separador de campos do conteúdo é o pipe ( | ).
Exemplo de Request Body conforme arquivo de exemplo: nfse_request_post_cancelar.txt
2.2.2.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 200 (Solicitação enviada com sucesso)
2.2.2.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
10
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Http status: 400, 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
2.2.3. MarcarConsultado:
2.2.3.1. Introdução
Método para indicar ao WebService que determinados documentos já foram consultados e não precisam
mais ser retornados na consulta (GET).
Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de
retorno.
2.2.3.2. URL:
<host>:<port>/<webservice>/api/dfe
2.2.3.3. Exemplo URL:
http://localhost:8080/webservice/api/dfe (instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/dfe (ambiente de homologação do SaaS)
2.2.3.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG.
action Ação solicitada MarcarConsultado Sim
ids Listagem de ids dos processamentos a serem
marcados como consultados. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
2.2.3.5. Permissões
Permissões conforme cadastro de usuários:
- NFS-e Integrador (ROLE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
11
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
2.2.3.6. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- -
2.2.3.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids" com uma
lista de ids com RPSs a serem marcados.
Exemplo de Request Body conforme arquivo de exemplo:
nfse_request_post_marcar_consultado.txt
2.2.3.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 200 (Solicitação enviada com sucesso)
2.2.3.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
2.2.4. ConsultarRpssAguardandoDownload:
2.2.4.1. Introdução
Método para consultar RPSs que estão com status de aguardando download no portal. Serão retornados
os arquivos que devem ser utilizados nos portais das prefeituras.
2.2.4.2. URL:
url: <host>:<port>/<webservice>/api/dfe
12
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
2.2.4.3. Exemplo URL:
http://localhost:8080/webservice/api/dfe (instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/dfe (ambiente de homologação do SaaS)
2.2.4.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG
action Ação solicitada ConsultarRpssAguardandoDownload Sim
referencia Informar referência da empresa a
ser consultada. "00910509000171_12345678" Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
2.2.4.5. Permissões
Permissões conforme cadastro de usuários:
- NFS-e Integrador (ROLE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
2.2.4.6. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- -
2.2.4.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "referencia" com
Exemplo de Request Body conforme arquivo de exemplo:
nfse_request_post_consultar_rpss_aguardando_download.txt
13
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
2.2.4.8. Retorno Sucesso
Response Body: {"formatoArquivo":"","body":"","result":"OK"}
Http status: 200 (Solicitação enviada com sucesso)
2.2.4.8.1. Layout Retorno
CAMPO DESCRIÇÃO
formatoArquivo Formato do arquivo que está sendo retornado: TXT ou XML
body Conteúdo do arquivo.
result
Consultar arquivo de exemplo: nfse_response_post_consultar_rpss_aguardando_download.txt
2.2.4.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 400, 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
2.2.5. UploadRetornoPrefeitura:
2.2.5.1. Introdução
No campo referencia informar na estrutura: <CNPJ>_<IM>_<UF>_<MUNICIPIO>#<nome arquivo de
retorno>.xml
2.2.5.2. URL:
<host>:<port>/<webservice>/api/dfe
2.2.5.3. Exemplo URL:
http://localhost:8080/webservice/api/dfe (instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/dfe (ambiente de homologação do SaaS)
14
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
2.2.5.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG
action Ação solicitada UploadRetornoPrefeitura Sim
referencia
Informar:
<CNPJ>_<IM>_<UF>_<MUNICIPIO
>#<nome arquivo de retorno>.xml
"00910509000171_12345678_SC_JOINVI
LLE#joinville - rps 3
arquivo_retorno_prefeitura_joinville.xml"
Sim
txt_conteudo
Conteúdo do arquivo recebido da
prefeitura para ser atualizado no
software.
*Outras tags informadas não serão utilizadas, portanto, não as informe.
2.2.5.5. Permissões
Permissões conforme cadastro de usuários:
- NFS-e Integrador (ROLE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
2.2.5.6. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- -
2.2.5.7. Envio
O corpo do POST (request body) deve ser um json contendo todos os campos do layout do método.
Exemplo de Request Body conforme arquivo de exemplo:
nfse_request_post_upload_retorno_prefeitura.txt
15
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
2.2.5.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 200 (Solicitação enviada com sucesso)
2.2.5.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 400, 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
2.2.6. Convertida:
2.2.6.1. Introdução
Método para consultar RPS já autorizados e que já foram marcadas como consultados.
2.2.6.2. URL:
<host>:<port>/<webservice>/api/dfe/convertida
2.2.6.3. Exemplo URL:
http://localhost:8080/webservice/api/dfe/convertida (instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/dfe/convertida (ambiente de homologação do SaaS)
2.2.6.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG
txt_conteudo Dados do RPS para consulta. Lista de campos que servirão de filtro
para o RPS. Sim
cnpjPrestador Atributo de txt_conteudo. CNPJ do
Prestador. Sim
inscricaoPrest
ador
Atributo de txt_conteudo.
Inscrição Municipal do Prestador. Sim
numeroRps Atributo de txt_conteudo. Numero Sim
16
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
do RPS.
serieRps Atributo de txt_conteudo. Série do
RPS. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
2.2.6.5. Permissões
Permissões conforme cadastro de usuários:
- NFS-e Integrador (ROLE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
2.2.6.6. Cabeçalho
Detalhes que devem ser informados na requisição:
- o usuário e
a senha fornecidos.
- -
2.2.6.7. Envio
O corpo do POST (request body) deve ser um json contendo todos os campos do layout do método.
Exemplo de Request Body conforme arquivo de exemplo: nfse_request_post_convertida.txt
2.2.6.8. Retorno Sucesso
Response Body: {"ids":[],"rpss":[]}
Http status: 200
2.2.6.8.1. Layout Retorno
CAMPO DESCRIÇÃO
ids Listagem dos IDs dos processamentos.
rpss Listagem dos RPSs.
17
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Os campos numéricos retornarão sem aspas, demais campos serão retornados entre .
Consultar arquivo de exemplo: nfse_response_convertida.txt
2.2.6.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 400, 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
2.3. MÉTODO: GET
2.3.1. Consulta Padrão
2.3.1.1. Introdução
Método para obter os retornos dos documentos enviados e a lista de documentos não consultados.
2.3.1.2. URL:
<host>:<port>/<webservice>/api/dfe
2.3.1.3. Filtro de Série e Quantidade de Resultados (maxResults):
Pode ser informado os parâmetros de Série NF-e e MaxResults para realizar a busca.
Quando não informada quantidade no parâmetro maxResults, será considerada a quantidade de 50
(cinquenta) results para cada consulta.
2.3.1.4. Exemplo URL:
http://localhost:8080/webservice/api/dfe (instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/dfe (ambiente de homologação do SaaS)
http://localhost:8080/webservice/api/dfe?maxResults=100&serie=001 (instalação in house)
Ou
18
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
https://ws.h.dfe.mastersaf.com.br/api/dfe?maxResults=100&serie=001 (ambiente de homologação do
SaaS)
2.3.1.5. Permissões
Permissões conforme cadastro de usuários:
- NFS-e Integrador (ROLE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
2.3.1.6. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
2.3.1.7. Envio
Nenhum dado além do cabeçalho deverá ser informado.
2.3.1.8. Retorno Sucesso
Response Body: {"retorno":{"ids":[],"rpss":[]}}
Http status: 200
2.3.1.8.1. Layout Retorno
CAMPO DESCRIÇÃO
retorno Conteúdo do retorno. Possui uma lista dos IDs dos
processamentos e uma listagens de seus respectivos RPSs.
ids Listagem dos IDs dos processamentos.
rpss Listagem dos RPSs.
No método GET, o resultado dos campos numéricos retornarão sem aspas, demais campos serão
.
19
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Consultar arquivo de exemplo: nfse_response_get.txt
2.3.1.9. Retorno Erro
Não há
3. MÓDULO NFE (MERCANTIL)
3.1. OBSERVAÇÕES GERAIS
Resumindo o processo, primeiramente é enviado um pacote de dados; depois é feita uma consulta
recebendo uma lista de ids e, então por fim, marcam-se no sistema os ids consultados para que numa
próxima consulta eles não sejam retornados novamente.
Para todos os requests é preciso usar basic authentication utilizando o usuário e a senha fornecidos.
Com isso basta realizar POST para enviar os pacotes e GET para consultar o resultado do
processamento. O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag
"txt_conteudo".
O txt_conteudo é formado por um objeto json, cujo atributo "xml" deve ser preenchido com o xml padrão
SEFAZ.
3.2. MÉTODO: POST
3.2.1. EnviarPacote:
3.2.1.1. Introdução
Método para envio de NF-es para serem autorizadas pela Sefaz correspondente.
3.2.1.2. URL:
<host>:<port>/<webservice>/api/nfe
3.2.1.3. Exemplo URL:
http://localhost:8080/webservice/api/nfe (instalação in house)
20
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
ou
https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologação do SaaS)
3.2.1.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG.
action Ação solicitada EnviarPacote Sim
referencia Nome do arquivo utilizado na integração. Não
txt_conteudo Grupo de informação da NF-e Sim
xml Conteúdo do XML de NF-e. Informar dados do
NF-e conforme layout padrão da Receita Federal. Sim
mastersaf Informações para contingência ou parâmetros
para filtro de impressão. Não
id_integrador Nome do integrador responsável pelo envio do
documento. Não
*Outras tags informadas não serão utilizadas, portanto, não as informe.
3.2.1.5. Permissões
Permissões conforme cadastro de usuários:
- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
3.2.1.6. Cabeçalho
Detalhes que devem ser informados na requisição:
- preciso usar basic authentication utilizando o usuário e
a senha fornecidos.
- -
3.2.1.7. Envio
O corpo do POST (request body) deve ser um json contendo todos os campos do layout do método.
Exemplo de Request Body conforme arquivo de exemplo: nfe_request_post_enviar_pacote_1.txt
21
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Caso necessite de contingencia na origem preencher o atributo "mastersaf", exemplo:
nfe_request_post_enviar_pacote_2.txt e nfe_request_post_enviar_pacote_3.txt
3.2.1.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 202
3.2.1.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 400, 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
3.2.2. Cancelar
3.2.2.1. Introdução
Método para cancelar NF-es enviados ao webservice.
3.2.2.2. URL:
<host>:<port>/<webservice>/api/nfe
3.2.2.3. Exemplo URL:
http://localhost:8080/webservice/api/nfe (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologação do SaaS)
3.2.2.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG.
action Ação solicitada Sim
referencia Nome do arquivo de integração Não
txt_conteudo Grupo de informações de cancelamento. Sim
22
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
xml Conteúdo do Cancelamento de NF-e. Informar dados de
Cancelamento da NF-e conforme layout padrão do produto. Sim
id_integrador Nome do integrador responsável pelo envio do documento. Não
*Outras tags informadas não serão utilizadas, portanto, não as informe.
3.2.2.5. Permissões
Permissões conforme cadastro de usuários:
- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
3.2.2.6. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- -
3.2.2.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "txt_conteudo".
O txt_conteudo é posicional separado por ";"(ponto-e-virgula).
Exemplo de Request Body conforme arquivo de exemplo: nfe_request_post_cancelar.txt
3.2.2.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 200 (Solicitação enviada com sucesso)
3.2.2.9. Retorno Erro
23
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Response Body: {"result":"<descrição do erro>"}
Http status: 400, 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
3.2.3. Inutilizar
3.2.3.1. Introdução
Método para inutilizar numerações de NF-es que ainda não foram utilizadas.
3.2.3.2. URL:
<host>:<port>/<webservice>/api/nfe
3.2.3.3. Exemplo URL:
http://localhost:8080/webservice/api/nfe (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologação do SaaS)
3.2.3.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG.
action Ação solicitada Sim
referencia Nome do arquivo de integração Não
txt_conteudo Grupo de informações de inutilização. Sim
xml Conteúdo da Inutilização de NF-e. Informar
dados conforme layout padrão do produto. Sim
id_integrador Nome do integrador responsável pelo envio
do documento. Não
*Outras tags informadas não serão utilizadas, portanto, não as informe.
3.2.3.5. Permissões
Permissões conforme cadastro de usuários:
- NF-e Integrador (ROLE_NFE_INTEGRADOR)
24
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
3.2.3.6. Cabeçalho
Detalhes que devem ser informados na requisição:
- dos os requests é preciso usar basic authentication utilizando o usuário e
a senha fornecidos.
- -
3.2.3.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "txt_conteudo".
O txt_conteudo é posicional separado por ";"(ponto-e-virgula).
Exemplo de Request Body conforme arquivo de exemplo: nfe_request_post_inutilizar.txt
3.2.3.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 200 (Solicitação enviada com sucesso)
3.2.3.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 400, 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
3.2.4. EnviarCartaCorrecaoNfe
3.2.4.1. Introdução
Método para emitir cartas de correção para NF-es já autorizadas.
25
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
3.2.4.2. URL:
<host>:<port>/<webservice>/api/nfe
3.2.4.3. Exemplo URL:
http://localhost:8080/webservice/api/nfe (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologação do SaaS)
3.2.4.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG
action Ação solicitada Sim
referencia Nome do arquivo de integração Não
txt_conteudo Grupo de informações de carta de correção. Sim
xml
Conteúdo da Carta de Correção de NF-e.
Informar dados conforme layout padrão do
produto.
Sim
id_integrador Nome do integrador responsável pelo envio do
documento. Não
*Outras tags informadas não serão utilizadas, portanto, não as informe.
3.2.4.5. Permissões
Permissões conforme cadastro de usuários:
- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
3.2.4.6. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
26
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
- -
3.2.4.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "txt_conteudo".
O txt_conteudo é posicional separado por ";"(ponto-e-virgula).
Exemplo de Request Body conforme arquivo de exemplo:
nfe_request_post_enviar_carta_correcao_nfe.txt
3.2.4.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 200 (Solicitação enviada com sucesso)
3.2.4.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 400, 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
3.2.5. MarcarConsultado
3.2.5.1. Introdução
Método para indicar ao WebService que determinados documentos já foram consultados e não precisam
mais ser retornados na consulta (GET).
Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de
retorno.
3.2.5.2. URL:
<host>:<port>/<webservice>/api/nfe
3.2.5.3. Exemplo URL:
http://localhost:8080/webservice/api/nfe (instalação in house)
27
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
ou
https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologação do SaaS)
3.2.5.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG.
action Ação solicitada MarcarConsultado Sim
ids Listagem de ids dos processamentos a serem
marcados como consultados. Sim
id_integrador Nome do integrador responsável pelo envio
do documento. Não
*Outras tags informadas não serão utilizadas, portanto, não as informe.
3.2.5.5. Permissões
Permissões conforme cadastro de usuários:
- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
3.2.5.6. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- -
3.2.5.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids".
Exemplo de Request Body conforme arquivo de exemplo: nfe_request_post_marcar_consultado.txt
3.2.5.8. Retorno Sucesso
Response Body: {"result":"OK"}
28
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Http status: 200 (Solicitação enviada com sucesso)
3.2.5.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
3.2.6. MarcarImpresso
3.2.6.1. Introdução
Método para indicar ao WebService que determinados documentos já foram impressos e não precisam
mais ser retornados na consulta (GET).
Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de
retorno.
3.2.6.2. URL:
<host>:<port>/<webservice>/api/nfe
3.2.6.3. Exemplo URL:
http://localhost:8080/webservice/api/nfe (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologação do SaaS)
3.2.6.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG
action Ação solicitada Sim
ids Grupo de informações para marcar como impresso. Sim
idProcessamento Id do processamento a ser marcado. Sim
idNota Id da nota a ser marcada. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
29
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
3.2.6.5. Permissões
Permissões conforme cadastro de usuários:
- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
3.2.6.6. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- -
3.2.6.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids".
Exemplo de Request Body conforme arquivo de exemplo: nfe_request_post_marcar_impresso.txt
3.2.6.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 200 (Solicitação enviada com sucesso)
3.2.6.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
3.2.7. MarcarCartaCorrecaoImpresso
3.2.7.1. Introdução
30
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Método para indicar ao WebService que determinados Cartas de Correção já foram impressos e não
precisam mais ser retornados na consulta (GET).
Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de
retorno.
3.2.7.2. URL:
<host>:<port>/<webservice>/api/nfe
3.2.7.3. Exemplo URL:
http://localhost:8080/webservice/api/nfe (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologação do SaaS)
3.2.7.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG
Action Ação solicitada MarcarCartaCorrecaoImpresso Sim
Ids Grupo de informações para marcar
como impresso. Sim
idProcessamento Id do processamento a ser marcado. Sim
idNota Id da CCe a ser marcada. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
3.2.7.5. Permissões
Permissões conforme cadastro de usuários:
- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
3.2.7.6. Cabeçalho
Detalhes que devem ser informados na requisição:
31
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
-
a senha fornecidos.
- -
3.2.7.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids".
Exemplo de Request Body conforme arquivo de exemplo:
nfe_request_post_marcar_carta_correcao_impresso.txt
3.2.7.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 200 (Solicitação enviada com sucesso)
3.2.7.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
3.2.8. ReimpressaoDanfe
3.2.8.1. Introdução
Método para solicitar reimpressão de NF-es.
3.2.8.2. URL:
<host>:<port>/<webservice>/api/nfe
3.2.8.3. Exemplo URL:
http://localhost:8080/webservice/api/nfe (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologação do SaaS)
32
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
3.2.8.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG
action Ação solicitada ReimpressaoDanfe Sim
txt_conteudo Grupo de informações de reimpressão. Sim
xml Conteúdo da solicitação de Reimpressão de NF-e.
Informar dados conforme layout padrão do produto. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
3.2.8.5. Permissões
Permissões conforme cadastro de usuários:
- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
3.2.8.6. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- -
3.2.8.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "txt_conteudo".
O txt_conteudo é posicional separado por ";"(ponto-e-virgula).
Exemplo de Request Body conforme arquivo de exemplo: nfe_request_post_reimpressao_danfe.txt
3.2.8.8. Retorno Sucesso
Response Body: {"result":"OK"}
33
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Http status: 200 (Solicitação enviada com sucesso)
3.2.8.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 400, 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
3.2.9. Consultar Cadastro
3.2.9.1. Introdução
Método para envio de Consultas de Cadastros pela Sefaz correspondente.
3.2.9.2. URL:
<host>:<port>/<webservice>/api/nfe
3.2.9.3. Exemplo URL:
http://localhost:8080/webservice/api/nfe (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologação do SaaS)
3.2.9.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG
action Ação solicitada Sim
referencia Nome do arquivo utilizado na integração. Não
txt_conteudo Grupo de informação da consulta. Sim
xml Conteúdo da Consulta do Cadastro conforme layout padrão
do produto. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
3.2.9.4.1. Detalhamento campo XML
CAMPO DESCRIÇÃO CONTEÚDO TIPO TAMANHO
--consulta_cadastro_ini--
versao Versão do Layout 2.00 Caractere 4
34
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
CNPJ CNPJ da empresa. Identificação da empresa
para o qual será
retornado a consulta.
Caractere 14
IE Inscrição Estadual da
empresa. Caractere
0-14
UF_pesquisa UF à qual se destina a
consulta. Caractere
2
IE_pesquisa Inscrição Estadual a ser
consultada. Somente um dos campos
deve ser preenchido.
Caractere 0-14
CNPJ_pesquisa CNPJ a ser consultado. Caractere 14
CPF_pesquisa CPF a ser consultado. Caractere 11
--consulta_cadastro_fim--
--arquivo_fim--
3.2.9.5. Permissões
Permissões conforme cadastro de usuários:
- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
3.2.9.6. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- -
3.2.9.7. Envio
O corpo do POST (request body) deve ser um json contendo todos os campos do layout do método.
3.2.9.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 202
35
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
3.2.9.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 400, 412, 500.
3.3. MÉTODO: GET
3.3.1. Consulta Padrão:
3.3.1.1. Introdução
Método para obter os retornos dos documentos enviados, lista de documentos não consultados, dados
de lotes inutilizados, dados de cartas de correção emitidas e os documentos que devem ser enviados
para o Printer imprimir.
3.3.1.2. URL:
<host>:<port>/<webservice>/api/nfe
3.3.1.3. Definir quantidade de Results da consulta:
<host>:<port>/<webservice>/api/nfe?maxResults=
Quando informada quantidade no parâmetro, será considerada a quantidade máxima de results para
cada lista e grupo de retorno (impressao[], impressaoCce[], retorno{...}).
Quando não informada quantidade no parâmetro, será considerada a quantidade de 50 (cinquenta)
results para cada lista e grupo de retorno (impressao[], impressaoCce[], retorno{...}).
3.3.1.4. Exemplo URL:
http://localhost:8080/webservice/api/nfe (instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologação do SaaS)
http://localhost:8080/webservice/api/nfe?maxResults=100 (instalação in house)
Ou
36
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
https://ws.h.dfe.mastersaf.com.br/api/nfe?maxResults=100 (ambiente de homologação do SaaS)
3.3.1.5. Permissões
Permissões conforme cadastro de usuários:
- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
3.3.1.6. Cabeçalho
Detalhes que devem ser informados na requisição:
- uário e
a senha fornecidos.
3.3.1.7. Envio
Nenhum dado além do cabeçalho deverá ser informado.
3.3.1.8. Retorno Sucesso
Response Body:
{
"impressao": [],
"impressaoCCe": [],
"retorno": {
"loteCartaCorrecao": [],
"consultaCadastro": [],
"nfes": [],
"ids": [],
"loteInutilizado": []
}
} Http status: 200
37
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
3.3.1.8.1. Layout Retorno
CAMPO DESCRIÇÃO
Impressao Lista documentos para impressão.
impressaoCce Lista documentos de Carta de Correção para impressão.
idProcessamento processamento.
params
retorno Grupo de informações para geração dos arquivos de retorno.
ids Listagem dos IDs dos processamentos que constam
como não consultados.
nfes Atributo de Listagem dos retornos das NF-es que foram processadas
pelo software.
loteCartaCorrecao Listagem dos retornos das Cartas de Correção enviadas.
loteInutilizado Inutilizações enviadas.
consultaCadastro
Detalhamento de campos específicos do Layout Retorno
CAMPO DESCRIÇÃO
nfes.nota.urlDanfePortal
Disponibilizamos o link para abertura do DANFE.
Este novo campo deverá ser preenchido somente nos retornos em que o status de
NF-e permita a impressão de DANFE (Autorizada ou Cancelada).
Para funcionamento da geração do link do DANFE, o preenchimento do campo “URL
de acesso ao portal” da tela Administração do Sistema > Extrato do Sistema torna-se
obrigatório.
Para a visualização do DANFE o usuário deverá ter a permissão “NF-e Visualizar”
habilitada em seu perfil.
Exemplo:
nfes":[{"nota":{"urlDanfePortal":"https://h.dfe.mastersaf.com.br/mvc/nfe/pdf/visualizar
Danfe/12345",
Consultar arquivo de exemplo: nfe_response_get.txt e nfe_response_get_cadastro.txt
3.3.1.9. Retorno Erro
38
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Não há
3.3.2. GetXml
3.3.2.1. Introdução
Método para obter o XML processado da respectiva chave de NF-e.
3.3.2.2. URL:
<host>:<port>/<webservice>/api/nfe/<chave nfe>/getXml
3.3.2.3. Exemplo URL:
http://localhost:8080/webservice/api/nfe/<chave nfe>/getXml
(instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/nfe/<chave nfe>/getXml
(ambiente de homologação do SaaS)
3.3.2.4. Permissões
Permissões conforme cadastro de usuários:
- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
3.3.2.5. Cabeçalho
Detalhes que devem ser informados na requisição:
- é preciso usar basic authentication utilizando o usuário e
a senha fornecidos.
- - -8859- Para o xml retornar com a codificação
correta.
39
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
3.3.2.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
3.3.2.7. Retorno Sucesso
Response Body: XML processado.
Http status: 200
Consultar arquivo de exemplo: nfe_response_get_xml.txt
3.3.2.8. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 203, 404, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
3.3.3. GetXmlCancelamento
3.3.3.1. Introdução
Método para obter o XML cancelado da respectiva chave de NF-e.
3.3.3.2. URL:
<host>:<port>/<webservice>/api/nfe/<chave nfe>/getXmlCancelamento
3.3.3.3. Exemplo URL:
http://localhost:8080/webservice/api/nfe/<chave nfe>/getXmlCancelamento
(instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/nfe/<chave nfe>/getXmlCancelamento
(ambiente de homologação do SaaS)
3.3.3.4. Permissões
40
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Permissões conforme cadastro de usuários:
- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
3.3.3.5. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- - -8859- Para o xml retornar com a codificação
correta.
3.3.3.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
3.3.3.7. Retorno Sucesso
Response Body: XML de cancelamento processado.
Http status: 200
Consultar arquivo de exemplo: nfe_response_get_xml_cancelado.txt
3.3.3.8. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 203, 404, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
3.3.4. GetDanfe
3.3.4.1. Introdução
Método para obter o DANFE da respectiva chave de NF-e.
41
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
3.3.4.2. URL:
<host>:<port>/<webservice>/api/nfe/<chave nfe>/getDanfe
3.3.4.3. Exemplo URL:
http://localhost:8080/webservice/api/nfe/<chave nfe>/getDanfe
(instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/nfe/<chave nfe>/getDanfe
(ambiente de homologação do SaaS)
3.3.4.4. Permissões
Permissões conforme cadastro de usuários:
- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
3.3.4.5. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
3.3.4.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
3.3.4.7. Retorno Sucesso
Response Body: retornará um array de bytes (byte[]). Esse retorno terá de ser escrito em disco com
Http status: 200
42
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
3.3.4.8. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 203, 404, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
3.3.5. GetStatus
3.3.5.1. Introdução
Método para obter o Status (Código-Descrição) da respectiva chave de NF-e.
3.3.5.2. URL:
<host>:<port>/<webservice>/api/nfe/<chave nfe>/getStatus
3.3.5.3. Exemplo URL:
http://localhost:8080/webservice/api/nfe/<chave nfe>/ getStatus
(instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/nfe/<chave nfe>/ getStatus
(ambiente de homologação do SaaS)
3.3.5.4. Permissões
Permissões conforme cadastro de usuários:
- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
3.3.5.5. Cabeçalho
Detalhes que devem ser informados na requisição:
43
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
- requests é preciso usar basic authentication utilizando o usuário e
a senha fornecidos.
3.3.5.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
3.3.5.7. Retorno Sucesso
Response Body: {retorno":{"loteCartaCorrecao":[],"nfes":[],"ids":[],"loteInutilizado":[]}}
Http status: 200
3.3.5.8. Layout Retorno
CAMPO DESCRIÇÃO
retorno Grupo de informações para geração dos arquivos de retorno.
ids não consultados.
nfes -es que foram processadas
pelo software.
loteCartaCorrecao
loteInutilizado nutilizações enviadas.
3.3.5.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 203, 404, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
3.3.6. GetStatus (com parâmetros)
3.3.6.1. Introdução
Método para obter o Status (Código-Descrição) de NF-e apartir de um conjunto de filtros.
3.3.6.2. URL:
44
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
<host>:<port>/<webservice>/api/nfe/getStatus
3.3.6.3. Filtro de CNPJ Emissor, Número da NF-e e Série da NF-e:
É necessário informar os parâmetros de CNPJ Emissor, Número NF-e e Série NF-e para realizar a busca.
Todos os parâmetros são obrigatórios.
3.3.6.4. Exemplo URL:
http://localhost:8080/webservice/api/nfe/getStatus?cnpjEmissor=1234567890&numeroNfe=1000&ser
ie=730
(instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/nfe/getStatus?cnpjEmissor=1234567890&numeroNfe=1000&se
rie=730
(ambiente de homologação do SaaS)
3.3.6.5. Permissões
Permissões conforme cadastro de usuários:
- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
3.3.6.6. Cabeçalho
Detalhes que devem ser informados na requisição:
- o usuário e
a senha fornecidos.
3.3.6.7. Envio
Nenhum dado além do cabeçalho deverá ser informado.
45
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
3.3.6.8. Retorno Sucesso
Response Body: {retorno":{"loteCartaCorrecao":[],"nfes":[],"ids":[],"loteInutilizado":[]}}
Http status: 200
3.3.6.9. Layout Retorno
CAMPO DESCRIÇÃO
retorno Grupo de informações para geração dos arquivos de retorno.
ids não consultados.
nfes -es que foram processadas
pelo software.
loteCartaCorrecao
loteInutilizado
3.3.6.10. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 203, 404, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
3.3.7. Consulta Retorno:
3.3.7.1. Introdução
Método para obter os retornos dos documentos enviados, lista de documentos não consultados, dados
de lotes inutilizados e dados de cartas de correção.
3.3.7.2. URL:
<host>:<port>/<webservice>/api/nfe/getRetorno
3.3.7.3. Definir quantidade de Results da consulta:
<host>:<port>/<webservice>/api/nfe/getRetorno?maxResults=
46
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Quando não informada quantidade no parâmetro, será considerada a quantidade de 50 (cinquenta)
results para cada consulta.
3.3.7.4. Filtro de Série
Para filtrar a consulta pela série, a mesma deverá ser enviada na URL. Se houver mais de uma, separá-
las por vírgula.
3.3.7.5. Exemplo URL com filtro:
http://localhost:8085/webservice/api/nfe/getRetorno/serie=700
Ou
http://localhost:8085/webservice/api/nfe/getRetorno/serie=700,701,703
http://localhost:8085/webservice/api/nfe/getRetorno/serie=700?maxResults=100
Ou
http://localhost:8085/webservice/api/nfe/getRetorno/serie=700,701,703?maxResults=100
3.3.7.6. Exemplo URL sem filtro:
http://localhost:8080/webservice/api/nfe/getRetorno (instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/nfe/getRetorno (ambiente de homologação do SaaS)
http://localhost:8080/webservice/api/nfe/getRetorno?maxResults=100 (instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/nfe/getRetorno?maxResults=100 (ambiente de homologação do
SaaS)
3.3.7.7. Permissões
Permissões conforme cadastro de usuários:
- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
47
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
3.3.7.8. Cabeçalho
Detalhes que devem ser informados na requisição:
- utilizando o usuário e
a senha fornecidos.
3.3.7.9. Envio
Nenhum dado além do cabeçalho deverá ser informado.
3.3.7.10. Retorno Sucesso
Response Body: {retorno":{"loteCartaCorrecao":[],"nfes":[],"ids":[],"loteInutilizado":[]}}
Http status: 200
3.3.7.10.1. Layout Retorno
CAMPO DESCRIÇÃO
retorno Grupo de informações para geração dos arquivos de retorno.
ids não consultados.
nfes -es que foram processadas
pelo software.
loteCartaCorrecao
loteInutilizado
Consultar arquivo de exemplo: nfe_response_getRetorno.txt
3.3.7.11. Retorno Erro
Não há
3.3.8. Consulta Impressão:
3.3.8.1. Introdução
48
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Método para obter os retornos dos documentos que devem ser enviados para o Printer imprimir.
3.3.8.2. URL:
<host>:<port>/<webservice>/api/nfe/getImpressao
3.3.8.3. Exemplo URL:
http://localhost:8080/webservice/api/nfe/getImpressao (instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/nfe/getImpressao (ambiente de homologação do SaaS)
3.3.8.4. Permissões
Permissões conforme cadastro de usuários:
- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
3.3.8.5. Cabeçalho
Detalhes que devem ser informados na requisição:
- é preciso usar basic authentication utilizando o usuário e
a senha fornecidos.
3.3.8.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
3.3.8.7. Retorno Sucesso
Response Body: {"impressao":[], "impressaoCCe":[]}
Http status: 200
49
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
3.3.8.7.1. Layout Retorno
CAMPO DESCRIÇÃO
impressao Lista documentos para impressão.
impressaoCCe Lista de eventos de carta de correção para impressão.
idProcessamento
params
Consultar arquivo de exemplo: nfe_response_getImpressao.txt
3.3.8.8. Retorno Erro
Não há
3.3.9. Consulta Impressão NFe:
3.3.9.1. Introdução
Método para obter apenas os retornos dos documentos de NF-e que devem ser enviados para o Printer
imprimir. Após o retorno, o sistema marca os documentos como
não são mais retornados pelo método.
3.3.9.2. URL:
<host>:<port>/<webservice>/api/nfe/getImpressaoNfe
3.3.9.3. Exemplo URL:
http://localhost:8080/webservice/api/nfe/getImpressaoNfe (instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/nfe/getImpressaoNfe(ambiente de homologação do SaaS)
3.3.9.4. Permissões
Permissões conforme cadastro de usuários:
- NF-e Integrador (ROLE_NFE_INTEGRADOR)
50
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
3.3.9.5. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
3.3.9.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
3.3.9.7. Retorno Sucesso
Response Body: {"impressao":[]}
Http status: 200
3.3.9.7.1. Layout Retorno
CAMPO DESCRIÇÃO
impressao Lista documentos para impressão.
idProcessamento
params
Consultar arquivo de exemplo: nfe_response_getImpressaoNfe.txt
3.3.9.8. Retorno Erro
Não há
3.3.10. Consulta Impressão Carta Correção NFe:
3.3.10.1. Introdução
51
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Método para obter apenas os retornos dos documentos de CC NF-e que devem ser enviados para o
Printer imprimir.
impressã
3.3.10.2. URL:
<host>:<port>/<webservice>/api/nfe/getImpressaoCcNfe
3.3.10.3. Exemplo URL:
http://localhost:8080/webservice/api/nfe/getImpressaoCcNfe (instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/nfe/getImpressaoCcNfe(ambiente de homologação do SaaS)
3.3.10.4. Permissões
Permissões conforme cadastro de usuários:
- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
3.3.10.5. Cabeçalho
Detalhes que devem ser informados na requisição:
- usar basic authentication utilizando o usuário e
a senha fornecidos.
3.3.10.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
3.3.10.7. Retorno Sucesso
Response Body: {"impressao":[]}
Http status: 200
52
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
3.3.10.7.1. Layout Retorno
CAMPO DESCRIÇÃO
impressaoCCe Lista de eventos de carta de correção para impressão.
idProcessamento
params
Consultar arquivo de exemplo: nfe_response_getImpressaoCcNfe.txt
3.3.10.8. Retorno Erro
Não há
4. MÓDULO CTE
4.1. OBSERVAÇÕES GERAIS
Resumindo o processo, primeiramente é enviado um pacote de dados; depois é feita uma consulta
recebendo uma lista de ids e, então por fim, marcam-se no sistema os ids consultados para que numa
próxima consulta eles não sejam retornados novamente, também são retornados os CT-es para
impressão via printer.
Para todos os requests é preciso usar basic authentication utilizando o usuário e a senha fornecidos.
Com isso basta realizar POST para enviar os pacotes e GET para consultar o resultado do
processamento. O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag
"txt_conteudo".
O separador de campos do conteúdo é o pipe ( | ). Para quebra de linha usa-se \n.
Para enviar vários CT-es você deve concatenar as strings antes de colocar em txt_conteúdo (txt conteúdo
terá vários "{"config": " .. ", "xml" : "..."} separando-os por vírgula. No caso de cancelamento e
inutilização o procedimento é o mesmo.
4.2. MÉTODO: POST
53
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
4.2.1. EnviarPacote:
4.2.1.1. Introdução
Método para envio de CT-es para serem autorizadas pela Sefaz correspondente.
4.2.1.2. URL:
<host>:<port>/<webservice>/api/cte
4.2.1.3. Exemplo URL:
http://localhost:8080/webservice/api/cte (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologação do SaaS)
4.2.1.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG
action Ação solicitada Sim
referencia Nome do arquivo utilizado na integração. Não
txt_conteudo Grupo de informações do CT-e Sim
xml Conteúdo do XML de CT-e. Informar dados conforme
layout padrão da Receita Federal. Sim
config Configurações. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
4.2.1.5. Permissões
Permissões conforme cadastro de usuários:
- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
4.2.1.6. Cabeçalho
54
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- - application/json
4.2.1.7. Envio
O corpo do POST (request body) deve ser um json contendo todos os campos do layout do método.
Exemplo de Request Body conforme arquivo de exemplo: cte_request_post_enviar_pacote.txt
4.2.1.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 202
4.2.1.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 400, 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
4.2.2. Cancelar
4.2.2.1. Introdução
Método para cancelar CT-es enviados ao webservice.
4.2.2.2. URL:
<host>:<port>/<webservice>/api/cte
4.2.2.3. Exemplo URL:
http://localhost:8080/webservice/api/cte (instalação in house)
ou
55
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologação do SaaS)
4.2.2.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG.
action Ação solicitada Sim
referencia Nome do arquivo de integração Não
txt_conteudo Grupo de informações de cancelamento. Sim
xml Conteúdo do Cancelamento de CT-e. Informar dados
conforme layout padrão da Receita Federal. Sim
config Configurações. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
4.2.2.5. Permissões
Permissões conforme cadastro de usuários:
- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
4.2.2.6. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- -
4.2.2.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "txt_conteudo".
Exemplo de Request Body conforme arquivo de exemplo: cte_request_post_cancelar.txt
4.2.2.8. Retorno Sucesso
56
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Response Body: {"result":"OK"}
Http status: 200 (Solicitação enviada com sucesso)
4.2.2.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 400, 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
4.2.3. EnviarCartaCorrecaoCte
4.2.3.1. Introdução
Método para emitir cartas de correção para CT-es já autorizadas.
4.2.3.2. URL:
<host>:<port>/<webservice>/api/cte
4.2.3.3. Exemplo URL:
http://localhost:8080/webservice/api/cte (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologação do SaaS)
4.2.3.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG
action Ação solicitada Sim
referencia Nome do arquivo de integração Não
txt_conteudo Grupo de informações de carta de correção. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
4.2.3.5. Permissões
Permissões conforme cadastro de usuários:
57
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
- NF-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
- CT-e Carta Correção (ROLE_CTE_CARTA_CORRECAO)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
4.2.3.6. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- -
4.2.3.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "txt_conteudo".
O txt_conteudo é posicional separado por ";"(ponto-e-virgula).
Exemplo de Request Body conforme arquivo de exemplo:
cte_request_post_carta_correcao.txt
4.2.3.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 200 (Solicitação enviada com sucesso)
4.2.3.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 400, 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
4.2.4. Inutilizar
4.2.4.1. Introdução
58
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Método para inutilizar numerações de CT-es que ainda não foram utilizadas.
4.2.4.2. URL:
<host>:<port>/<webservice>/api/cte
4.2.4.3. Exemplo URL:
http://localhost:8080/webservice/api/cte (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologação do SaaS)
4.2.4.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG.
action Ação solicitada Sim
referencia Nome do arquivo de integração Não
txt_conteudo Grupo de informações de inutilização. Sim
xml Conteúdo da Inutilização de CT-e. Informar dados
conforme layout padrão da Receita Federal. Sim
config Configurações. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
4.2.4.5. Permissões
Permissões conforme cadastro de usuários:
- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
4.2.4.6. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
59
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
- -
4.2.4.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "txt_conteudo".
Exemplo de Request Body conforme arquivo de exemplo: cte_request_post_inutilizar.txt
4.2.4.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 200 (Solicitação enviada com sucesso)
4.2.4.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 400, 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
4.2.5. MarcarConsultado
4.2.5.1. Introdução
Método para indicar ao WebService que determinados documentos já foram consultados e não precisam
mais ser retornados na consulta (GET).
Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de
retorno.
4.2.5.2. URL:
<host>:<port>/<webservice>/api/cte
4.2.5.3. Exemplo URL:
http://localhost:8080/webservice/api/cte (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologação do SaaS)
60
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
4.2.5.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG
action Ação solicitada Sim
ids Listagem de ids dos processamentos a serem marcados
como consultados. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
4.2.5.5. Permissões
Permissões conforme cadastro de usuários:
- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
4.2.5.6. Cabeçalho
Detalhes que devem ser informados na requisição:
- odos os requests é preciso usar basic authentication utilizando o usuário e
a senha fornecidos.
- -
4.2.5.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids".
Exemplo de Request Body conforme arquivo de exemplo: cte_request_post_marcar_consultado.txt
4.2.5.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 200 (Solicitação enviada com sucesso)
4.2.5.9. Retorno Erro
61
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Response Body: {"result":"<descrição do erro>"}
Http status: 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
4.2.6. MarcarImpresso
4.2.6.1. Introdução
Método para indicar ao WebService que determinados documentos já foram impressos e não precisam
mais ser retornados na consulta (GET).
Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de
retorno.
4.2.6.2. URL:
<host>:<port>/<webservice>/api/cte
4.2.6.3. Exemplo URL:
http://localhost:8080/webservice/api/cte (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologação do SaaS)
4.2.6.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG
action Ação solicitada Sim
ids Grupo de informações para marcar como impresso. Sim
idProcessamento Id do processamento a ser marcado. Sim
idNota Id da nota a ser marcada. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
4.2.6.5. Permissões
Permissões conforme cadastro de usuários:
- CT-e Integrador (ROLE_CTE_INTEGRADOR)
62
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
4.2.6.6. Cabeçalho
Detalhes que devem ser informados na requisição:
- utilizando o usuário e
a senha fornecidos.
- -
4.2.6.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids".
Exemplo de Request Body conforme arquivo de exemplo: cte_request_post_marcar_impresso.txt
4.2.6.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 200 (Solicitação enviada com sucesso)
4.2.6.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
4.2.7. MarcarCartaCorrecaoImpresso
4.2.7.1. Introdução
Método para indicar ao WebService que determinadas Cartas de Correção já foram impressos e não
precisam mais ser retornados na consulta (GET).
Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de
retorno.
63
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
4.2.7.2. URL:
<host>:<port>/<webservice>/api/cte
4.2.7.3. Exemplo URL:
http://localhost:8080/webservice/api/cte (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologação do SaaS)
4.2.7.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG
action Ação solicitada CartaCorrecaoImpresso Sim
ids Grupo de informações para marcar
como impresso. Sim
idProcessamento Id do processamento a ser marcado. Sim
idNota Id da CCe a ser marcada. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
4.2.7.5. Permissões
Permissões conforme cadastro de usuários:
- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
4.2.7.6. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- -
64
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
4.2.7.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids".
Exemplo de Request Body conforme arquivo de exemplo:
cte_request_post_marcar_carta_correcao_impresso.txt
4.2.7.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 200 (Solicitação enviada com sucesso)
4.2.7.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
4.3. MÉTODO: GET
4.3.1. Consulta Padrão
4.3.1.1. Introdução
Método para obter os retornos dos documentos enviados, lista de documentos não consultados, dados
de lotes inutilizados e os documentos que devem ser enviados para o Printer imprimir.
4.3.1.2. URL:
<host>:<port>/<webservice>/api/cte
4.3.1.3. Definir quantidade de Results da consulta:
<host>:<port>/<webservice>/api/cte?maxResults=
Quando informada quantidade no parâmetro, será considerada a quantidade máxima de results para
cada lista e grupo de retorno (impressao[], retorno{...}).
65
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Quando não informada quantidade no parâmetro, será considerada a quantidade de 50 (cinquenta)
results para cada lista e grupo de retorno (impressao[], retorno{...}).
4.3.1.4. Exemplo URL:
http://localhost:8080/webservice/api/cte (instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologação do SaaS)
http://localhost:8080/webservice/api/cte?maxResults=100 (instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/cte?maxResults=100 (ambiente de homologação do SaaS)
4.3.1.5. Permissões
Permissões conforme cadastro de usuários:
- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
4.3.1.6. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
4.3.1.7. Envio
Nenhum dado além do cabeçalho deverá ser informado.
4.3.1.8. Retorno Sucesso
Response Body:
{"impressao":[],"retorno":{"loteCartaCorrecao":[],"nfes":[],"ids":[],"loteInutilizado":[]}}
66
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Http status: 200
4.3.1.8.1. Layout Retorno
CAMPO DESCRIÇÃO
impressao Lista documentos para impressão.
id
nota Atribu .
retorno Grupo de informações para geração dos arquivos de retorno.
ids tam como não
consultados.
ctes CT-es que foram processadas pelo
software.
loteInutilizado
Consultar arquivo de exemplo: cte_response_get.txt
4.3.1.9. Retorno Erro
Não há
4.3.2. GetXml
4.3.2.1. Introdução
Método para obter o XML processado da respectiva chave de CT-e.
4.3.2.2. URL:
<host>:<port>/<webservice>/api/cte/<chave cte>/getXml
4.3.2.3. Exemplo URL:
http://localhost:8080/webservice/api/cte/<chave cte>/getXml
(instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/cte/<chave cte>/getXml
67
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
(ambiente de homologação do SaaS)
4.3.2.4. Permissões
Permissões conforme cadastro de usuários:
- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
4.3.2.5. Cabeçalho
Detalhes que devem ser informados na requisição:
- usuário e
a senha fornecidos.
- - -8859- Para o xml retornar com a codificação
correta.
4.3.2.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
4.3.2.7. Retorno Sucesso
Response Body: XML processado.
Http status: 200
Consultar arquivo de exemplo: cte_response_get_xml.txt
4.3.2.8. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 203, 404, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
68
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
4.3.3. GetXmlCancelamento
4.3.3.1. Introdução
Método para obter o XML cancelado da respectiva chave de CT-e.
4.3.3.2. URL:
<host>:<port>/<webservice>/api/cte/<chave cte>/getXmlCancelamento
4.3.3.3. Exemplo URL:
http://localhost:8080/webservice/api/cte/<chave cte>/getXmlCancelamento
(instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/cte/<chave cte>/getXmlCancelamento
(ambiente de homologação do SaaS)
4.3.3.4. Permissões
Permissões conforme cadastro de usuários:
- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
4.3.3.5. Cabeçalho
Detalhes que devem ser informados na requisição:
- odos os requests é preciso usar basic authentication utilizando o usuário e
a senha fornecidos.
- - -8859- Para o xml retornar com a codificação
correta.
4.3.3.6. Envio
69
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Nenhum dado além do cabeçalho deverá ser informado.
4.3.3.7. Retorno Sucesso
Response Body: XML de cancelamento processado.
Http status: 200
Consultar arquivo de exemplo: cte_response_get_xml_cancelamento.txt
4.3.3.8. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 203, 404, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
4.3.4. GetDacte
4.3.4.1. Introdução
Método para obter o DACTE da respectiva chave de CT-e.
4.3.4.2. URL:
<host>:<port>/<webservice>/api/cte/<chave cte>/getDacte
4.3.4.3. Exemplo URL:
http://localhost:8080/webservice/api/cte/<chave cte>/getDacte
(instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/cte/<chave cte>/getDacte
(ambiente de homologação do SaaS)
4.3.4.4. Permissões
Permissões conforme cadastro de usuários:
70
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
4.3.4.5. Cabeçalho
Detalhes que devem ser informados na requisição:
- todos os requests é preciso usar basic authentication utilizando o usuário e
a senha fornecidos.
4.3.4.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
4.3.4.7. Retorno Sucesso
Response Body: retornará um array de bytes (byte[]). Esse retorno terá de ser escrito em disco com
Http status: 200
4.3.4.8. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 203, 404, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
4.3.5. GetStatus
4.3.5.1. Introdução
Método para obter o STATUS da respectiva chave de CT-e.
4.3.5.2. URL:
host>:<port>/<webservice>/api/cte/<chave cte>/getStatus
71
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
4.3.5.3. Exemplo URL:
http://localhost:8080/webservice/api/cte/<chave cte>/ getStatus
(instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/cte/<chave cte>/ getStatus
(ambiente de homologação do SaaS)
4.3.5.4. Permissões
Permissões conforme cadastro de usuários:
- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
4.3.5.5. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
4.3.5.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
4.3.5.7. Retorno Sucesso
Http status: 200
4.3.5.8. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 203, 404, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
72
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
4.3.6. Consulta Retorno
4.3.6.1. Introdução
Método para obter os retornos dos documentos enviados, lista de documentos não consultados e dados
de lotes inutilizados.
4.3.6.2. URL:
<host>:<port>/<webservice>/api/cte/getRetorno
4.3.6.3. Definir quantidade de Results da consulta:
<host>:<port>/<webservice>/api/cte/getRetorno?maxResults=
Quando não informada quantidade no parâmetro, será considerada a quantidade de 50 (cinquenta)
results para cada consulta.
4.3.6.4. Filtro de Série
Para filtrar a consulta pela série, a mesma deverá ser enviada na URL. Se houver mais de uma, separá-
las por vírgula.
4.3.6.5. Exemplo URL com filtro:
http://localhost:8085/webservice/api/cte/getRetorno/serie=700
Ou
http://localhost:8085/webservice/api/cte/getRetorno/serie=700,701,703
http://localhost:8085/webservice/api/cte/getRetorno/serie=700?maxResults=100
Ou
http://localhost:8085/webservice/api/cte/getRetorno/serie=700,701,703?maxResults=100
4.3.6.6. Exemplo URL sem filtro:
http://localhost:8080/webservice/api/cte/getRetorno (instalação in house)
Ou
73
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
https://ws.h.dfe.mastersaf.com.br/api/cte/getRetorno (ambiente de homologação do SaaS)
4.3.6.7. Permissões
Permissões conforme cadastro de usuários:
- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
4.3.6.8. Cabeçalho
Detalhes que devem ser informados na requisição:
- usar basic authentication utilizando o usuário e
a senha fornecidos.
4.3.6.9. Envio
Nenhum dado além do cabeçalho deverá ser informado.
4.3.6.10. Retorno Sucesso
Response Body: {"retorno":{"loteCartaCorrecao":[],"nfes":[],"ids":[],"loteInutilizado":[]}}
Http status: 200
4.3.6.10.1. Layout Retorno
CAMPO DESCRIÇÃO
retorno Grupo de informações para geração dos arquivos de retorno.
ids consultados.
ctes CT-es que foram processadas pelo
software.
loteInutilizado
Consultar arquivo de exemplo: cte_response_getRetorno.txt
74
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
4.3.6.11. Retorno Erro
Não há
4.3.7. Consulta Impressão
4.3.7.1. Introdução
Método para obter os retornos dos documentos que devem ser enviados para o Printer imprimir.
4.3.7.2. URL:
<host>:<port>/<webservice>/api/cte/getImpressao
4.3.7.3. Exemplo URL:
http://localhost:8080/webservice/api/cte/getImpressao (instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/cte/getImpressao (ambiente de homologação do SaaS)
4.3.7.4. Permissões
Permissões conforme cadastro de usuários:
- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
4.3.7.5. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
4.3.7.6. Envio
75
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Nenhum dado além do cabeçalho deverá ser informado.
4.3.7.7. Retorno Sucesso
Response Body: {"impressao":[], "impressaoCCe":[]}
Http status: 200
4.3.7.7.1. Layout Retorno
CAMPO DESCRIÇÃO
impressao Lista documentos para impressão.
impressoCCe Lista de eventos de carta de correção para impressão.
id
nota
Consultar arquivo de exemplo: cte_response_getImpressao.txt
4.3.7.8. Retorno Erro
Não há
5. MÓDULO MDFE
5.1. OBSERVAÇÕES GERAIS
Resumindo o processo, primeiramente é enviado um pacote de dados; depois é feita uma consulta
recebendo uma lista de ids e, então por fim, marcam-se no sistema os ids consultados para que numa
próxima consulta eles não sejam retornados novamente, também são retornados os MDF-es para
impressão via printer.
Para todos os requests é preciso usar basic authentication utilizando o usuário e a senha fornecidos.
Com isso basta realizar POST para enviar os pacotes e GET para consultar o resultado do
processamento. O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag
"txt_conteudo".
O separador de campos do conteúdo é o pipe ( | ). Para quebra de linha usa-se \n.
76
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Para enviar vários MDF-es você deve concatenar as strings antes de colocar em txt_conteúdo.Txt
conteúdo terá vários "{"config": " .. ", "xml" : "..."} separando-os por vírgula. No caso de cancelamento e
encerramento o procedimento é o mesmo.
5.2. MÉTODO: POST
5.2.1. EnviarPacote:
5.2.1.1. Introdução
Método para envio de MDF-es para serem autorizadas pela Sefaz correspondente.
5.2.1.2. URL:
<host>:<port>/<webservice>/api/mdfe
5.2.1.3. Exemplo URL:
http://localhost:8080/webservice/api/mdfe (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/mdfe (ambiente de homologação do SaaS)
5.2.1.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG.
action Ação solicitada Sim
referencia Nome do arquivo utilizado na integração. Não
txt_conteudo Grupo de informações do MDF-e Sim
xml Conteúdo do XML de MDF-e. Informar dados
conforme layout padrão da Receita Federal. Sim
config Configurações. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
5.2.1.5. Permissões
Permissões conforme cadastro de usuários:
77
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
5.2.1.6. Cabeçalho
Detalhes que devem ser informados na requisição:
- o usuário e
a senha fornecidos.
- -
5.2.1.7. Envio
O corpo do POST (request body) deve ser um json contendo todos os campos do layout do método.
Exemplo de Request Body conforme arquivo de exemplo: mdfe_request_post_enviar_pacote.txt
5.2.1.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 202
5.2.1.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 400, 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
5.2.2. Cancelar
5.2.2.1. Introdução
Método para cancelar MDF-es enviados ao webservice.
5.2.2.2. URL:
78
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
<host>:<port>/<webservice>/api/mdfe
5.2.2.3. Exemplo URL:
http://localhost:8080/webservice/api/mdfe (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/mdfe (ambiente de homologação do SaaS)
5.2.2.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG
action Ação solicitada Sim
referencia Nome do arquivo de integração Não
txt_conteudo Grupo de informações de cancelamento. Sim
xml
Conteúdo do Cancelamento de MDF-e. Informar dados
conforme layout padrão da Receita Federal mais a tag <IE>
para ser utilizada em processos internos.
Sim
config Configurações. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
5.2.2.5. Permissões
Permissões conforme cadastro de usuários:
- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
5.2.2.6. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- -
79
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
5.2.2.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "txt_conteudo".
Exemplo de Request Body conforme arquivo de exemplo: mdfe_request_post_cancelar.txt
5.2.2.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 200 (Solicitação enviada com sucesso)
5.2.2.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 400, 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
5.2.3. Encerrar
5.2.3.1. Introdução
Método para encerrar MDF-es.
5.2.3.2. URL:
<host>:<port>/<webservice>/api/mdfe
5.2.3.3. Exemplo URL:
http://localhost:8080/webservice/api/mdfe (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/mdfe (ambiente de homologação do SaaS)
5.2.3.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG.
action Ação solicitada Encerrar Sim
80
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
referencia Nome do arquivo de integração Não
txt_conteudo Grupo de informações de inutilização. Sim
xml
Conteúdo da Inutilização de MDF-e. Informar dados
conforme layout padrão da Receita Federal mais a tag <IE>
para ser utilizada em processos internos.
Sim
config Configurações. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
5.2.3.5. Permissões
Permissões conforme cadastro de usuários:
- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
5.2.3.6. Cabeçalho
Detalhes que devem ser informados na requisição:
- authentication utilizando o usuário e
a senha fornecidos.
- -
5.2.3.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "txt_conteudo".
Exemplo de Request Body conforme arquivo de exemplo: mdfe_request_post_encerrar.txt
5.2.3.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 200 (Solicitação enviada com sucesso)
5.2.3.9. Retorno Erro
81
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Response Body: {"result":"<descrição do erro>"}
Http status: 400, 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
5.2.4. MarcarConsultado
5.2.4.1. Introdução
Método para indicar ao WebService que determinados documentos já foram consultados e não precisam
mais ser retornados na consulta (GET).
Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de
retorno.
5.2.4.2. URL:
<host>:<port>/<webservice>/api/mdfe
5.2.4.3. Exemplo URL:
http://localhost:8080/webservice/api/mdfe (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/mdfe (ambiente de homologação do SaaS)
5.2.4.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG.
action Ação solicitada Sim
ids Listagem de ids dos processamentos a
serem marcados como consultados. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
5.2.4.5. Permissões
Permissões conforme cadastro de usuários:
- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
82
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
5.2.4.6. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- -
5.2.4.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids".
Exemplo de Request Body conforme arquivo de exemplo: mdfe_request_post_marcar_consultado.txt
5.2.4.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 200 (Solicitação enviada com sucesso)
5.2.4.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
5.2.5. MarcarImpresso
5.2.5.1. Introdução
Método para indicar ao WebService que determinados documentos já foram impressos e não precisam
mais ser retornados na consulta (GET).
Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de
retorno.
83
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
5.2.5.2. URL:
<host>:<port>/<webservice>/api/mdfe
5.2.5.3. Exemplo URL:
http://localhost:8080/webservice/api/mdfe (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/mdfe (ambiente de homologação do SaaS)
5.2.5.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG
action Ação solicitada Sim
ids Grupo de informações para marcar como impresso. Sim
idProcessamento Id do processamento a ser marcado. Sim
idNota Id da nota a ser marcada. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
5.2.5.5. Permissões
Permissões conforme cadastro de usuários:
- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
5.2.5.6. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- -
5.2.5.7. Envio
84
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids".
Exemplo de Request Body conforme arquivo de exemplo: mdfe_request_post_marcar_impresso.txt
5.2.5.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 200 (Solicitação enviada com sucesso)
5.2.5.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
5.3. MÉTODO: GET
5.3.1. Consulta Padrão
5.3.1.1. Introdução
Método para obter os retornos dos documentos enviados, lista de documentos não consultados, dados
de lotes inutilizados e os documentos que devem ser enviados para o Printer imprimir.
5.3.1.2. URL:
<host>:<port>/<webservice>/api/mdfe
5.3.1.3. Exemplo URL:
http://localhost:8080/webservice/api/mdfe (instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/mdfe (ambiente de homologação do SaaS)
5.3.1.4. Permissões
Permissões conforme cadastro de usuários:
85
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
5.3.1.5. Cabeçalho
Detalhes que devem ser informados na requisição:
- é preciso usar basic authentication utilizando o usuário e
a senha fornecidos.
5.3.1.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
5.3.1.7. Retorno Sucesso
Response Body: {"impressao":[],"retorno":{"mdfeCtes":[],"ids":[]}}
Http status: 200
5.3.1.7.1. Layout Retorno
CAMPO DESCRIÇÃO
impressao Lista documentos para impressão.
id
nota
retorno Grupo de informações para geração dos arquivos de retorno.
ids consultados.
mdfeCtes MDF-es que foram processadas pelo
software.
Consultar arquivo de exemplo: mdfe_response_get.txt
5.3.1.8. Retorno Erro
86
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Não há
5.3.2. GetXml
5.3.2.1. Introdução
Método para obter o XML de envio da respectiva chave de MDF-e.
5.3.2.2. URL:
<host>:<port>/<webservice>/api/mdfe/<chave cte>/getXml
5.3.2.3. Exemplo URL:
http://localhost:8080/webservice/api/mdfe/<chave cte>/getXml
(instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/mdfe/<chave cte>/getXml
(ambiente de homologação do SaaS)
5.3.2.4. Permissões
Permissões conforme cadastro de usuários:
- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
5.3.2.5. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- - -8859- Para o xml retornar com a codificação
correta.
87
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
5.3.2.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
5.3.2.7. Retorno Sucesso
Response Body: XML processado.
Http status: 200
Consultar arquivo de exemplo: mdfe_response_get_xml.txt
5.3.2.8. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 203, 404, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
5.3.3. Consulta Retorno
5.3.3.1. Introdução
Método para obter os retornos dos documentos enviados, lista de documentos não consultados e dados
de lotes inutilizados.
5.3.3.2. URL:
<host>:<port>/<webservice>/api/mdfe/getRetorno
5.3.3.3. Definir quantidade de Results da consulta:
<host>:<port>/<webservice>/api/mdfe/getRetorno?maxResults=
Quando não informada quantidade no parâmetro, será considerada a quantidade de 50 (cinquenta)
results para cada consulta.
5.3.3.4. Filtro de Série
88
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Para filtrar a consulta pela série, a mesma deverá ser enviada na URL. Se houver mais de uma, separá-
las por vírgula.
5.3.3.5. Exemplo URL com filtro:
http://localhost:8085/webservice/api/mdfe/getRetorno/serie=700
Ou
http://localhost:8085/webservice/api/mdfe/getRetorno/serie=700,701,703
http://localhost:8085/webservice/api/mdfe/getRetorno/serie=700?maxResults=100
Ou
http://localhost:8085/webservice/api/mdfe/getRetorno/serie=700,701,703?maxResults=100
5.3.3.6. Exemplo URL sem filtro:
http://localhost:8080/webservice/api/mdfe/getRetorno (instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/mdfe/getRetorno (ambiente de homologação do SaaS)
5.3.3.7. Permissões
Permissões conforme cadastro de usuários:
- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
5.3.3.8. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
5.3.3.9. Envio
Nenhum dado além do cabeçalho deverá ser informado.
89
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
5.3.3.10. Retorno Sucesso
Response Body: {"retorno":{"mdfeCtes":[],"ids":[]}}
Http status: 200
5.3.3.10.1. Layout Retorno
CAMPO DESCRIÇÃO
retorno Grupo de informações para geração dos arquivos de retorno.
ids consultados.
mdfeCtes -es que foram processadas pelo
software.
Consultar arquivo de exemplo: mdfe_response_getRetorno.txt
5.3.3.11. Retorno Erro
Não há
5.3.4. Consulta Impressão
5.3.4.1. Introdução
Método para obter os retornos dos documentos que devem ser enviados para o Printer imprimir.
5.3.4.2. URL:
<host>:<port>/<webservice>/api/mdfe/getImpressao
5.3.4.3. Exemplo URL:
http://localhost:8080/webservice/api/mdfe/getImpressao (instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/mdfe/getImpressao (ambiente de homologação do SaaS)
90
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
5.3.4.4. Permissões
Permissões conforme cadastro de usuários:
- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
5.3.4.5. Cabeçalho
Detalhes que devem ser informados na requisição:
- é preciso usar basic authentication utilizando o usuário e
a senha fornecidos.
5.3.4.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
5.3.4.7. Retorno Sucesso
Response Body: {"impressao":[]}
Http status: 200
5.3.4.7.1. Layout Retorno
CAMPO DESCRIÇÃO
impressao Lista documentos para impressão.
id
nota
Consultar arquivo de exemplo: mdfe_response_getImpressao.txt
5.3.4.8. Retorno Erro
Não há
91
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
5.3.5. GetDamdfe
5.3.5.1. Introdução
Método para obter o DAMDFE da respectiva chave de MDF-e.
5.3.5.2. URL:
<host>:<port>/<webservice>/api/mdfe/<chave mdfe>/getDamdfe
5.3.5.3. Exemplo URL:
http://localhost:8080/webservice/api/mdfe/<chave mdfe>/getDamdfe
(instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/mdfe/<chave mdfe>/getDamdfe
(ambiente de homologação do SaaS)
5.3.5.4. Permissões
Permissões conforme cadastro de usuários:
- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
5.3.5.5. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
5.3.5.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
92
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
5.3.5.7. Retorno Sucesso
Response Body: retornará um array de bytes (byte[]). Esse retorno terá de ser escrito em disco com
Http status: 200
5.3.5.8. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 203, 404, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
6. MÓDULO RECEPTOR NFSE (SERVIÇO)
6.1. OBSERVAÇÕES GERAIS
Existem poucos métodos para esse módulo, existe somente um método POST (MarcarConsultado) e um
método GET (Consulta Padrão).
Resumindo o processo, é feita uma consulta recebendo uma lista de ids e, então por fim, marcam-se no
sistema os ids consultados para que, numa próxima consulta, eles não sejam retornados novamente.
6.2. Método: POST
6.2.1. MarcarConsultado:
6.2.1.1. Introdução
Método para indicar ao WebService que determinados documentos já foram consultados e não precisam
mais ser retornados na consulta (GET).
Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de
retorno.
6.2.1.2. URL:
<host>:<port>/<webservice>/api/receptor_nfs
93
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
6.2.1.3. Exemplo URL:
http://localhost:8080/webservice/api/receptor_nfs (instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/receptor_nfs (ambiente de homologação do SaaS)
6.2.1.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG.
action Ação solicitada Sim
ids Listagem de ids dos processamentos a serem marcados
como consultados. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
6.2.1.5. Permissões
Permissões conforme cadastro de usuários:
- Administrar o sistema (ROLE_SUPER_ADMIN)
6.2.1.6. Cabeçalho
Detalhes que devem ser informados na requisição:
- usar basic authentication utilizando o usuário e
a senha fornecidos.
- -
6.2.1.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids" com uma
lista de ids dos documentos a serem marcados.
Exemplo de Request Body conforme arquivo de exemplo:
receptor_nfs_request_post_marcar_consultado.txt
94
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
6.2.1.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 200 (Solicitação enviada com sucesso)
6.2.1.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
6.3. MÉTODO: GET
6.3.1. Consulta Padrão
6.3.1.1. Introdução
Método para obter os retornos dos documentos recebidos e uma lista de documentos não consultados.
6.3.1.2. URL:
<host>:<port>/<webservice>/api/receptor_nfs
6.3.1.3. Exemplo URL:
http://localhost:8080/webservice/api/receptor_nfs (instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/receptor_nfs (ambiente de homologação do SaaS)
6.3.1.4. Permissões
Permissões conforme cadastro de usuários:
- Administrar o sistema (ROLE_SUPER_ADMIN)
6.3.1.5. Cabeçalho
95
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Detalhes que devem ser informados na requisição:
- usar basic authentication utilizando o usuário e
a senha fornecidos.
6.3.1.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
6.3.1.7. Retorno Sucesso
Response Body: {"retorno":{"ids":[],"nfss":[]}}
Http status: 200
Consultar arquivo de exemplo: receptor_nfse_response_get.txt
6.3.1.7.1. Layout Retorno
CAMPO DESCRIÇÃO
retorno Grupo de informações para geração dos arquivos de retorno.
ids consultados.
nfss -es que foram processadas pelo
software.
6.3.1.8. Retorno Erro
Não há
7. MÓDULO RECEPTOR NFE (MERCANTIL)
7.1. OBSERVAÇÕES GERAIS
Esse módulo necessita que sejam enviados os XMLs recebidos de fornecedores e depois que sejam
marcados como consultados.
Como em todos os módulos existe uma consulta padrão (GET) e também alguns métodos para consulta
de XMLs (processados e cancelados).
96
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
7.2. MÉTODO: POST
7.2.1. EnviarRecebimento
7.2.1.1. Introdução
Método para envio de NF-es de fornecedores ao WebService.
7.2.1.2. URL:
<host>:<port>/<webservice>/api/recebimentoNfe
7.2.1.3. Exemplo URL:
http://localhost:8080/webservice/api/recebimentoNfe (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe (ambiente de homologação do SaaS)
7.2.1.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG.
action Ação solicitada Sim
referencia Nome do arquivo utilizado na integração. Não
txt_conteudo Conteúdo do XML de NF-e. Informar dados
conforme layout padrão da Receita Federal. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
7.2.1.5. Permissões
Permissões conforme cadastro de usuários:
- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
97
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
7.2.1.6. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- -
7.2.1.7. Envio
O corpo do POST (request body) deve ser um json contendo todos os campos do layout do método.
Exemplo de Request Body conforme arquivo de exemplo:
receptor_nfe_request_post_enviar_recebimento.txt
7.2.1.8. Retorno Sucesso
Response Body: {"resul
Http status: 202
7.2.1.8.1. Layout Retorno
CAMPO DESCRIÇÃO
result
anoMes Ano e mês da emissão.
cnpjEmitente CNPJ do Emitente.
recebimento Tipo
cnpjDestinatario CNPJ do Destinatário.
Consultar arquivo de exemplo: receptor_nfe_response_post_enviar_recebimento.txt
7.2.1.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 400, 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
98
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
7.2.2. EnviarEventoManifestacao
7.2.2.1. Introdução
Método para envio de eventos de manifestação do destinatário.
7.2.2.2. URL:
<host>:<port>/<webservice>/api/recebimentoNfe
7.2.2.3. Exemplo URL:
http://localhost:8080/webservice/api/recebimentoNfe (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe (ambiente de homologação do SaaS)
7.2.2.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG
action Ação solicitada EnviarEventoManifestacao Sim
referencia Nome do arquivo utilizado na integração. Não
txt_conteudo Conteúdo do XML de NF-e. Informar dados
conforme layout padrão da Receita Federal. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
7.2.2.5. Permissões
Permissões conforme cadastro de usuários:
- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
7.2.2.6. Cabeçalho
Detalhes que devem ser informados na requisição:
99
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
-
a senha fornecidos.
- -
7.2.2.7. Envio
O corpo do POST (request body) deve ser um json contendo todos os campos do layout do método.
Exemplo de Request Body conforme arquivo de exemplo:
receptor_nfe_request_post_enviar_evento_manifestacao.txt
7.2.2.8. Retorno Sucesso
Response Body: {"result":"OK","descricao":"Evento [CIENCIA_OPERACAO] solicitado com sucesso."}
Http status: 202
7.2.2.8.1. Layout Retorno
CAMPO DESCRIÇÃO
result
descricao Descrição do resultado do envio.
Consultar arquivo de exemplo:
receptor_nfe_response_post_enviar_evento_manifestacao_ok.txt
7.2.2.9. Retorno Erro
Response Body: {"result": "erro","descricao": "Não foi encontrada nota recebida com chave de acesso:
12345 para a empresa com CNPJ: 000 e Inscrição Estadual: 000" }
Http status: 400, 412, 500.
Consultar arquivos de exemplo para erros:
receptor_nfe_response_post_enviar_evento_manifestacao_erro.txt
receptor_nfe_response_post_enviar_evento_manifestacao_erro_2.txt
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
100
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
7.2.3. MarcarConsultado:
7.2.3.1. Introdução
Método para indicar ao WebService que determinados documentos já foram consultados e não precisam
mais ser retornados na consulta (GET).
Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de
retorno.
7.2.3.2. URL:
<host>:<port>/<webservice>/api/recebimentoNfe
7.2.3.3. Exemplo URL:
http://localhost:8080/webservice/api/recebimentoNfe (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe (ambiente de homologação do SaaS)
7.2.3.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG.
action Ação solicitada Sim
ids Listagem de ids dos processamentos a serem
marcados como consultados. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
7.2.3.5. Permissões
Permissões conforme cadastro de usuários:
- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
7.2.3.6. Cabeçalho
Detalhes que devem ser informados na requisição:
101
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
-
a senha fornecidos.
- -
7.2.3.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids" com uma
lista de ids dos documentos a serem marcados.
Exemplo de Request Body conforme arquivo de exemplo:
receptor_nfe_request_post_marcar_consultado.txt
7.2.3.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 200 (Solicitação enviada com sucesso)
7.2.3.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
7.2.4. MarcarImpresso:
7.2.4.1. Introdução
Método para indicar ao WebService que determinados documentos já foram impressos e não precisam
mais ser retornados na consulta (GET).
Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de
retorno.
7.2.4.2. URL:
<host>:<port>/<webservice>/api/recebimentoNfe
102
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
7.2.4.3. Exemplo URL:
http://localhost:8080/webservice/api/recebimentoNfe (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe (ambiente de homologação do SaaS)
7.2.4.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG
action Ação solicitada Sim
ids Grupo de informações para marcar como impresso. Sim
idProcessamento Id do processamento a ser marcado. Sim
idNota Id da nota a ser marcada. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
7.2.4.5. Permissões
Permissões conforme cadastro de usuários:
- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
7.2.4.6. Cabeçalho
Detalhes que devem ser informados na requisição:
- authentication utilizando o usuário e
a senha fornecidos.
- -
7.2.4.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids".
Exemplo de Request Body conforme arquivo de exemplo:
receptor_nfe_request_post_marcar_impresso.txt
103
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
7.2.4.8. Retorno Sucesso
Response Body: {"result":"OK"}
Http status: 200 (Solicitação enviada com sucesso)
7.2.4.9. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
7.3. MÉTODO: GET
7.3.1. Consulta Padrão
7.3.1.1. Introdução
Método para obter os retornos dos documentos enviados e a lista de documentos não consultados.
7.3.1.2. URL:
<host>:<port>/<webservice>/api/recebimentoNfe
7.3.1.3. Exemplo URL:
http://localhost:8080/webservice/api/recebimentoNfe (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe (ambiente de homologação do SaaS)
7.3.1.4. Permissões
Permissões conforme cadastro de usuários:
- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
104
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
7.3.1.5. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
7.3.1.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
7.3.1.7. Retorno Sucesso
Response Body: {"retorno":{"recebimentos":[],"ids":[]}}
Http status: 200
7.3.1.7.1. Layout Retorno
CAMPO DESCRIÇÃO
Retorno Grupo de informações para geração dos arquivos de retorno.
Ids consultados.
Recebimentos NF-es que foram processadas pelo
software.
Consultar arquivo de exemplo: receptor_nfe_response_get.txt
7.3.1.8. Retorno Erro
Não há
7.3.2. GetXml
7.3.2.1. Introdução
Método para obter o XML processado da respectiva chave de NF-e.
105
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
7.3.2.2. URL:
<host>:<port>/<webservice>/api/recebimentoNfe/<chave nfe>/getXml
7.3.2.3. Exemplo URL:
http://localhost:8080/webservice/api/recebimentoNfe/<chave nfe>/getXml
(instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe/<chave nfe>/getXml
(ambiente de homologação do SaaS)
7.3.2.4. Permissões
Permissões conforme cadastro de usuários:
- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
7.3.2.5. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- - -8859- Para o xml retornar com a codificação
correta.
7.3.2.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
7.3.2.7. Retorno Sucesso
Response Body: XML processado.
106
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Http status: 200
Consultar arquivo de exemplo: receptor_nfe_response_get_xml.txt
7.3.2.8. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 203, 404, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
7.3.3. GetXmlCancelamento
7.3.3.1. Introdução
Método para obter o XML cancelado da respectiva chave de NFe.
7.3.3.2. URL:
<host>:<port>/<webservice>/api/recebimentoNfe/<chave nfe>/getXmlCancelamento
7.3.3.3. Exemplo URL:
http://localhost:8080/webservice/api/recebimentoNfe/<chave nfe>/getXmlCancelamento
(instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe/<chave nfe>/getXmlCancelamento
(ambiente de homologação do SaaS)
7.3.3.4. Permissões
Permissões conforme cadastro de usuários:
- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
107
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
7.3.3.5. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- - -8859- Para o xml retornar com a codificação
correta.
7.3.3.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
7.3.3.7. Retorno Sucesso
Response Body: XML de cancelamento processado.
Http status: 200
Consultar arquivo de exemplo: receptor_nfe_response_get_xml_cancelado.txt
7.3.3.8. Retorno Erro
Response Body: {"result":"<descrição do erro>"}
Http status: 203, 404, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
7.3.4. GetStatus
7.3.4.1. Introdução
Método para obter o Status (Código-Descrição) da respectiva chave de NF-e.
7.3.4.2. URL:
<host>:<port>/<webservice>/api/ recebimentoNfe/<chave nfe>/getStatus
108
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
7.3.4.3. Exemplo URL:
http://localhost:8080/webservice/api/recebimentoNfe/<chave nfe>/getStatus
(instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe/<chave nfe>/getStatus
(ambiente de homologação do SaaS)
7.3.4.4. Permissões
Permissões conforme cadastro de usuários:
- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
7.3.4.5. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
7.3.4.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
7.3.4.7. Retorno Sucesso
Response Body: {"retorno":{"recebimentos":[],"ids":[]}}
Http status: 200
7.3.4.8. Layout Retorno
CAMPO DESCRIÇÃO
Retorno Grupo de informações para geração dos arquivos de retorno.
Ids Não há.
109
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Recebimentos -es que foram solicitados.
7.3.4.9. Retorno Erro
Não há
7.3.5. Consulta Impressão
7.3.5.1. Introdução
Método para obter os retornos dos documentos que devem ser enviados para o Printer imprimir.
7.3.5.2. URL:
<host>:<port>/<webservice>/api/recebimentoNfe/getImpressao
7.3.5.3. Exemplo URL:
http://localhost:8080/webservice/api/recebimentoNfe/getImpressao (instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe/getImpressao (ambiente de homologação do
SaaS)
7.3.5.4. Permissões
Permissões conforme cadastro de usuários:
- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
7.3.5.5. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
110
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
7.3.5.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
7.3.5.7. Retorno Sucesso
Response Body: {"impressao":[]}
Http status: 200
7.3.5.7.1. Layout Retorno
CAMPO DESCRIÇÃO
impressao Lista documentos para impressão.
idProcessamento
params
Consultar arquivo de exemplo: receptor_nfe_response_getImpressao.txt
7.3.5.8. Retorno Erro
Não há
8. MÓDULO RECEPTOR CTE
8.1. OBSERVAÇÕES GERAIS
Esse módulo necessita que sejam enviados os XMLs recebidos e depois que sejam marcados como
consultados. É possível ainda consultar um documento e obter o seu XML.
Como em todos os módulos existe uma consulta padrão (GET) e também alguns métodos para consulta
de XMLs (processados e cancelados).
8.2. MÉTODO: POST
8.2.1. EnviarRecebimento
111
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
8.2.1.1. Introdução
Método para envio de NF-es de fornecedores ao WebService.
8.2.1.2. URL:
<host>:<port>/<webservice>/api/recebimento
8.2.1.3. Exemplo URL:
http://localhost:8080/webservice/api/recebimento (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/recebimento (ambiente de homologação do SaaS)
8.2.1.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG
action Ação solicitada Sim
referencia Nome do arquivo utilizado na integração. Não
txt_conteudo Conteúdo do XML de CT-e. Informar dados
conforme layout padrão da Receita Federal. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
8.2.1.5. Permissões
Permissões conforme cadastro de usuários:
- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
- Receptor CT-e Consultar Chave via Webservice (ROLE_RECEBIMENTO_CONSULTACHAVE_CTE)
- Receptor CT-e Resgatar XML via Webservice (ROLE_RECEBIMENTO_RESGATAXML_CTE)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
8.2.1.6. Cabeçalho
Detalhes que devem ser informados na requisição:
112
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
-
a senha fornecidos.
- -
8.2.1.7. Envio
O corpo do POST (request body) deve ser um json contendo todos os campos do layout do método.
Exemplo de Request Body conforme arquivo de exemplo:
receptor_cte_request_post_enviar_recebimento.txt
8.2.1.8. Retorno Sucesso
Response Body: { result : OK , anoMes : , cnpjEmitente : , recebimento : : }
Http status: 202
8.2.1.8.1. Layout Retorno
CAMPO DESCRIÇÃO
result
anoMes Ano e mês da emissão.
cnpjEmitente CNPJ do Emitente.
Recebimento
cnpjDestinatario CNPJ do Destinatário.
Consultar arquivo de exemplo: receptor_cte_response_post_enviar_recebimento.txt
8.2.1.9. Retorno Erro
Response Body: { result : <descrição do erro> }
Http status: 400, 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
8.2.2. ConsultarDocFornecedor
8.2.2.1. Introdução
113
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Método para consultar status de CT-e recebido. A consulta pode ser feita usando a chave do documento
ou através da combinação de CNPJ, IE, número e série.
8.2.2.2. URL:
<host>:<port>/<webservice>/api/recebimento
8.2.2.3. Exemplo URL:
http://localhost:8080/webservice/api/recebimento (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/recebimento (ambiente de homologação do SaaS)
8.2.2.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG
action Ação solicitada ConsultarDocFornecedor Sim
txt_conteudo Grupo de informações para consulta. Sim
tpDoc para consulta.
- Sim
chave
-e.
Informar quando não for informar os outros
Não
cnpj
informado.
Não
ie
Não
nrDoc
Número do CT-e.
informado.
Não
serie -e. Não
Não
*Outras tags informadas não serão utilizadas, portanto, não as informe.
8.2.2.5. Permissões
114
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Permissões conforme cadastro de usuários:
- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
- Receptor CT-e Consultar Chave via Webservice (ROLE_RECEBIMENTO_CONSULTACHAVE_CTE)
- Receptor CT-e Resgatar XML via Webservice (ROLE_RECEBIMENTO_RESGATAXML_CTE)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
8.2.2.6. Cabeçalho
Detalhes que devem ser informados na requisição:
- preciso usar basic authentication utilizando o usuário e
a senha fornecidos.
- -
8.2.2.7. Envio
O corpo do POST (request body) deve ser um json contendo todos os campos do layout do método.
Exemplo de Request Body conforme arquivo de exemplo (Consulta pela Chave):
receptor_cte_request_post_consultar_doc_fornecedor_1.txt
Exemplo de Request Body conforme arquivo de exemplo (Consulta pelos dados do CT-e):
receptor_cte_request_post_consultar_doc_fornecedor_2.txt
8.2.2.8. Retorno Sucesso
Response Body: { result : OK , status :100}
Http status: 202
8.2.2.8.1. Layout Retorno
CAMPO DESCRIÇÃO
result
status Código do status do documento.
115
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
8.2.2.9. Retorno Erro
Response Body: { result : <descrição do erro> }
Http status: 400, 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
8.2.3. ResgatarXmlFornecedor
8.2.3.1. Introdução
Método para resgatar XML de CT-e recebido. A consulta pode ser feita usando a chave do documento ou
através da combinação de CNPJ, IE, número e série.
8.2.3.2. URL:
<host>:<port>/<webservice>/api/recebimento
8.2.3.3. Exemplo URL:
http://localhost:8080/webservice/api/recebimento (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/recebimento (ambiente de homologação do SaaS)
8.2.3.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG
action Ação solicitada ResgatarXmlFornecedor Sim
txt_conteudo Grupo de informações para consulta. Sim
tpDoc Atributo
para consulta. - Sim
chave
-e.
Informar quando não for informar os outros
Não
cnpj Não
informado.
Não
116
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
ie
Não
nrDoc -e. Não
Não
serie -e. Não
Não
*Outras tags informadas não serão utilizadas, portanto, não as informe.
8.2.3.5. Permissões
Permissões conforme cadastro de usuários:
- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
- Receptor CT-e Consultar Chave via Webservice (ROLE_RECEBIMENTO_CONSULTACHAVE_CTE)
- Receptor CT-e Resgatar XML via Webservice (ROLE_RECEBIMENTO_RESGATAXML_CTE)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
8.2.3.6. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- ent-
8.2.3.7. Envio
O corpo do POST (request body) deve ser um json contendo todos os campos do layout do método.
Exemplo de Request Body conforme arquivo de exemplo (Consulta pela Chave):
receptor_cte_request_post_resgatar_xml_fornecedor_1.txt
Exemplo de Request Body conforme arquivo de exemplo (Consulta pelos dados do CT-e):
receptor_cte_request_post_resgatar_xml_fornecedor_2.txt
117
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
8.2.3.8. Retorno Sucesso
Response Body: { result : OK , status :100}
Http status: 202
8.2.3.8.1. Layout Retorno
CAMPO DESCRIÇÃO
result
xml Conteúdo do XML.
Consultar arquivo de exemplo: receptor_cte_response_post_resgatar_xml_fornecedor.txt
8.2.3.9. Retorno Erro
Response Body: { result : <descrição do erro> }
Http status: 400, 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
8.2.4. MarcarConsultado:
8.2.4.1. Introdução
Método para indicar ao WebService que determinados documentos já foram consultados e não precisam
mais ser retornados na consulta (GET).
Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de
retorno.
8.2.4.2. URL:
<host>:<port>/<webservice>/api/recebimento
8.2.4.3. Exemplo URL:
http://localhost:8080/webservice/api/recebimento (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/recebimento (ambiente de homologação do SaaS)
118
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
8.2.4.4. Layout
CAMPO DESCRIÇÃO CONTEÚDO OBRIG
action Ação solicitada Sim
ids Listagem de ids dos processamentos a serem marcados
como consultados. Sim
*Outras tags informadas não serão utilizadas, portanto, não as informe.
8.2.4.5. Permissões
Permissões conforme cadastro de usuários:
- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
- Receptor CT-e Consultar Chave via Webservice (ROLE_RECEBIMENTO_CONSULTACHAVE_CTE)
- Receptor CT-e Resgatar XML via Webservice (ROLE_RECEBIMENTO_RESGATAXML_CTE)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
8.2.4.6. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- -
8.2.4.7. Envio
O corpo do POST (request body) deve ser um json contendo uma tag action e uma tag ids com uma
lista de ids dos documentos a serem marcados.
Exemplo de Request Body conforme arquivo de exemplo:
receptor_cte_request_post_marcar_consultado.txt
8.2.4.8. Retorno Sucesso
119
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Response Body: { result : OK }
Http status: 200 (Solicitação enviada com sucesso)
8.2.4.9. Retorno Erro
Response Body: { result : <descrição do erro> }
Http status: 412, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
8.3. MÉTODO: GET
8.3.1. Consulta Padrão
8.3.1.1. Introdução
Método para obter os retornos dos documentos enviados e a lista de documentos não consultados.
8.3.1.2. URL:
<host>:<port>/<webservice>/api/recebimento
8.3.1.3. Exemplo URL:
http://localhost:8080/webservice/api/recebimento (instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/recebimento (ambiente de homologação do SaaS)
8.3.1.4. Permissões
Permissões conforme cadastro de usuários:
- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
- Receptor CT-e Consultar Chave via Webservice (ROLE_RECEBIMENTO_CONSULTACHAVE_CTE)
- Receptor CT-e Resgatar XML via Webservice (ROLE_RECEBIMENTO_RESGATAXML_CTE)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
120
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
8.3.1.5. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
8.3.1.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
8.3.1.7. Retorno Sucesso
Response Body: { retorno :{ recebimentos :[], ids :[]}}
Http status: 200
8.3.1.7.1. Layout Retorno
CAMPO DESCRIÇÃO
Retorno Grupo de informações para geração dos arquivos de retorno.
Ids ds dos processamentos que constam como não
consultados.
Recebimentos s CT-es que foram processadas pelo
software.
Consultar arquivo de exemplo: receptor_cte_response_get.txt
8.3.1.8. Retorno Erro
Não há
8.3.2. GetXml
8.3.2.1. Introdução
Método para obter o XML processado da respectiva chave de CT-e.
121
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
8.3.2.2. URL:
<host>:<port>/<webservice>/api/recebimento/<chave cte>/getXml
8.3.2.3. Exemplo URL:
http://localhost:8080/webservice/api/recebimento/<chave cte>/getXml
(instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/recebimento/<chave cte>/getXml
(ambiente de homologação do SaaS)
8.3.2.4. Permissões
Permissões conforme cadastro de usuários:
- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
- Receptor CT-e Consultar Chave via Webservice (ROLE_RECEBIMENTO_CONSULTACHAVE_CTE)
- Receptor CT-e Resgatar XML via Webservice (ROLE_RECEBIMENTO_RESGATAXML_CTE)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
8.3.2.5. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- - -8859- Para o xml retornar com a codificação
correta.
8.3.2.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
8.3.2.7. Retorno Sucesso
122
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Response Body: XML processado.
Http status: 200
Consultar arquivo de exemplo: receptor_cte_response_get_xml.txt
8.3.2.8. Retorno Erro
Response Body: { result : <descrição do erro> }
Http status: 203, 404, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
8.3.3. GetXmlCancelamento
8.3.3.1. Introdução
Método para obter o XML cancelado da respectiva chave de CT-e.
8.3.3.2. URL:
<host>:<port>/<webservice>/api/recebimento/<chave cte>/getXmlCancelamento
8.3.3.3. Exemplo URL:
http://localhost:8080/webservice/api/recebimento/<chave cte>/getXmlCancelamento
(instalação in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/recebimento/<chave cte>/getXmlCancelamento
(ambiente de homologação do SaaS)
8.3.3.4. Permissões
Permissões conforme cadastro de usuários:
- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
- Receptor CT-e Consultar Chave via Webservice (ROLE_RECEBIMENTO_CONSULTACHAVE_CTE)
- Receptor CT-e Resgatar XML via Webservice (ROLE_RECEBIMENTO_RESGATAXML_CTE)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
123
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
8.3.3.5. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
- - -8859- Para o xml retornar com a codificação
correta.
8.3.3.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
8.3.3.7. Retorno Sucesso
Response Body: XML de cancelamento processado.
Http status: 200
Consultar arquivo de exemplo: receptor_cte_response_get_xml_cancelado.txt
8.3.3.8. Retorno Erro
Response Body: { result : <descrição do erro> }
Http status: 203, 404, 500.
*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.
8.3.4. GetStatus
8.3.4.1. Introdução
Método para obter o Status (Código-Descrição) da respectiva chave de CT-e.
8.3.4.2. URL:
<host>:<port>/<webservice>/api/recebimento/<chave nfe>/getStatus
124
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
8.3.4.3. Exemplo URL:
http://localhost:8080/webservice/api/recebimento/<chave nfe>/getStatus
(instalação in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/recebimento/<chave nfe>/getStatus
(ambiente de homologação do SaaS)
8.3.4.4. Permissões
Permissões conforme cadastro de usuários:
- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usuário informado na requisição deve possuir ao menos uma destas permissões.
8.3.4.5. Cabeçalho
Detalhes que devem ser informados na requisição:
-
a senha fornecidos.
8.3.4.6. Envio
Nenhum dado além do cabeçalho deverá ser informado.
8.3.4.7. Retorno Sucesso
Response Body: { retorno :{ recebimentos :[], ids :[]}}
Http status: 200
8.3.4.8. Layout Retorno
CAMPO DESCRIÇÃO
Retorno Grupo de informações para geração dos arquivos de retorno.
Ids Não há.
125
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Recebimentos CT-es que foram solicitados.
8.3.4.9. Retorno Erro
Não há
9. LISTAGEM DE ERROS
- 203 Usuário e senha sem permissão de acessar o método/dados da empresa.
- 400 Erros ao de validação/parser/argumentos ilegais descritos no Response Body.
- 403 Forbidden Usuário e senha não foram informados corretamente.
- 404 Chave de acesso não encontrada.
- 412 JSON nao informado ou invalido ou nenhuma ação (campo action) encontrada.
- 415 Unsupported Media Type 125étodos125-type não foi informado corretamente.
- 500 Erro interno.
Mais informações sobre os códigos de retorno podem ser encontradas em:
http://en.wikipedia.org/wiki/List_of_http_status_codes
10. EXEMPLO DE COMO UTILIZAR O WEBSERVICE
10.1. OBSERVAÇÕES GERAIS
Utilize a extensão REST Client do Firefox para realizar os testes de comunicação.
http://restclient.net/
126
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
10.2. UTILIZANDO A EXTENSÃO REST CLIENT DO FIREFOX
10.2.1. Como informar os dados?
1º) Informar tipo de requisição
2º) Informar a URL:
3º) Informando usuário e senha:
127
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Informar o usuário e senha:
4º) Informando dados no cabeçalho (Content-type se necessário):
Selecionar menu
Informar dados de tipo de conteúdo, por exemplo:
128
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
5º) Informando conteúdo (corpo) da mensagem (se necessário):
10.2.2. Exemplo de POST
129
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
10.2.3. Exemplo de GET
11. PROGRAMA EXEMPLO EM JAVA
Junto deste Manual está disponível o código fonte de software capaz de testar os serviços oferecidos por
nosso WebService.
Depois de descompactá-lo siga os seguintes passos para utilizá-lo:
3) Importar este projeto no eclipse como um projeto maven. Para isto, acessar opção pelo menu File
-> Import -> Existing Maven Projects
2) Com o projeto importado, abrir a classe br.com.mastersaf.WSTest (Para testar método POST
enviarPacote da NF-e) ou br.com.mastersaf.WSPdfDacteTest (Teste para método GET getDacte do CT-e)
2.1) Configurar os atributos URL_WEBSERVICE, USER e PASSWORD
2.2) O usuário informado deverá ter a permissão de integrador no portal MASTERSAF.
130
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
2.3) Retornar no método getBodyRequest, o json da NFE com os seus dados. Este formato foi o mesmo
descrito neste manual.
12. RELAÇÃO DE MUDANÇAS DE VERSÕES DO MANUAL
Versão Data Mudanças Versão DF-e
1.00 22/08/2012 Criação do manual baseado em MASTERSAFDFE
Integração com Webservice.pdf -
1.01 25/09/2012 Incluído capítulo 5 MDF-E -
1.02 08/10/2012 Incluído item 3.3.4 GetDanfe -
1.03 29/11/2012
Incluído item 3.3.5 GetStatus
Incluído capítulo 12 Relação das Mudanças de Versões do
Manual
3.13.2
1.04 27/03/2013 Incluídos itens 3.3.6, 3.3.7, 4.3.5, 4.3.6, 5.3.3, 5.3.4 3.16.0
1.05 05/04/2013 Incluído exemplo de retorno do método GET para o módulo
Receptor NFS-e. 3.16.1
1.06 11/04/2013 Incluído item 7.2.2 referente a Eventos de Manifestação. 3.16.1
1.07 13/05/2013 Incluídos itens 3.3.6.3 e 3.3.6.4 referentes a Filtro do
método getRetorno. 3.17.0
1.08
26/06/2013
08/08/2013
Alterado nomes dos métodos getXmlCancelado para ficar
igual ao nome no produto (getXmlCancelamento).
Incluído item 4.3.5 GetStatus
3.19.1
1.09 16/08/2013
Incluída informação de charset na parte de cabeçalhos dos
métodos getXml e getXmlCancelamento para todos os
modulos
3.19.1
1.10 19/08/2013 Atualizado item 3.3.5.7 Retorno Sucesso
Adicionado item 3.3.5.8 Layout Retorno 3.19.2
1.11 20/09/2013
Adicionado item 2.3.1.3 Definir quantidade de Results da
consulta
Atualizado item 2.3.1.4 Exemplo URL
Adicionado item 3.3.1.3 Definir quantidade de Results da
consulta
Atualizado item 3.3.1.4 Exemplo URL
Atualizado item 3.3.1.8 Retorno Sucesso
Atualizado item 3.3.1.8.1 Layout Retorno
3.20.1
131
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
Adicionado item 3.3.6.3 Definir quantidade de Results da
consulta
Atualizado item 3.3.6.5 Exemplo URL com filtro
Atualizado item 3.3.6.6 Exemplo URL sem filtro
Adicionado item 4.3.1.3 Definir quantidade de Results da
consulta
Atualizado item 4.3.1.4 Exemplo URL
Adicionado item 4.3.6.3 Definir quantidade de Results da
consulta
Atualizado item 4.3.6.4 Exemplo URL
1.13 01/04/2014
Alteração deste manual para incluir um novo arquivo de
exemplo nfe_request_post_enviar_pacote_3.txt com todos
os 131étodos131f131 corretos referentes à 131étodos131f para
filtro de 131étodos131f. O mesmo encontra-se no pacote.
Alteração neste manual, no ponto 3.2.1.4 de post Nfe onde
diz: 131étodos131f Informações para contingência, pois
seguem mais informações, além das informações de
contingencia dentro do atributo 131étodos131f.
3.24.2
1.14 05/05/2014 Atualizado item 2.3.1.8.1 Layout Retorno
padronização do retorno. 3.25.2
1.15 22/07/2014 Incluído item: 4.2.3 EnviarCartaCorrecaoCte.
Atualizado 4.3.1 ConsultaPadrao módulo CT-e. 3.27.1
1.16 19/08/2014 Incluído item 2.2.6 Convertida, do módulo NFS-e. 3.28.0
1.17 02/09/2014
Incluido método getStatus para Recebimento NFE/CTE
Saas.
3.28.1
1.18 31/10/2014 Atualizado para alguns métodos do módulo nfe o novo
parâmetro na requisição id_integrador 3.30.0
1.19 25/11/2014 Atualizado a estrutura de retorno para 131étodos GET com
novo parâmetro contendo link de acesso direto ao DANFE. 3.30.1
1.20 29/12/2014 2.3.1 Consulta Padrão Atualizado parâmetros de filtro
disponíveis. 3.26.0
1.20 30/12/2014 3.2.7 MarcarCartaCorrecaoImpresso Incluindo método 3.13.0
1.20 30/12/2014 4.2.7 MarcarCartaCorrecaoImpresso Incluindo método 3.27.1
1.20 30/12/2014 4.3.6 Consulta Retorno Atualizado parâmetros de filtro
disponíveis. 3.25.3
132
MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3
Versão: 1.22 Atualizado em: 09/06/2015
1.20 30/12/2014 5.3.3 Consulta Retorno Atualizado parâmetros de filtro
disponíveis. 3.25.3
1.20 30/12/2014 5.3.5 GetDamdfe Incluindo método. 3.27.0
1.20 30/12/2014 7.2.4 MarcarImpresso Incluindo método 3.19.1
1.20 30/12/2014 7.3.5 Consulta Impressão Incluindo método 3.19.1
1.21 12/05/2015 Atualizando arquivos de exemplo de consulta de MDF-e.
Itens do manual: 5.3.1 e 5.3.3 3.34.1
1.21 12/05/2015
Atualizando arquivos de exemplo de consulta de NF-e. Itens
do manual:
3.3.1 - Consulta Padrão
3.3.7 - Consulta Retorno
3.34.1
1.21 12/05/2015
Atualizando arquivos de exemplo de consulta de CT-e. Itens
do manual:
4.3.1 - Consulta Padrão
4.3.7 - Consulta Retorno
3.34.1
13. SUPORTE TÉCNICO
Para dúvidas ou problemas, abra um chamado no Contact Center ou entre em contato com nossa equipe
de Suporte Técnico MASTERSAF pelo Telefone:
(11) 2159-0600 opção 02 (Atendimento das Soluções DFE).
Nosso horário de atendimento é de segunda à sexta-feira de 09h às 18h.