Anda di halaman 1dari 132

INTEGRAO COM WEBSERVICE

DFE V3

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

NDICE
1.

INTRODUO .............................................................................................................................................. 6

2.

MDULO NFSE (SERVIO) ......................................................................................................................... 6

2.1. OBSERVAES GERAIS ........................................................................................................................... 6


2.2. MTODO: 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. MTODO: GET ........................................................................................................................................ 17


2.3.1. CONSULTA PADRO ............................................................................................................................................ 17
3.

MDULO NFE (MERCANTIL) .................................................................................................................... 19

3.1. OBSERVAES GERAIS .......................................................................................................................... 19


3.2. MTODO: 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. MTODO: GET ........................................................................................................................................ 35


3.3.1. CONSULTA PADRO:............................................................................................................................................ 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 PARMETROS).......................................................................................................................... 43

3.3.7.

CONSULTA RETORNO: ......................................................................................................................................... 45

Verso: 1.22
Atualizado em: 09/06/2015

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

3.3.8.

CONSULTA IMPRESSO: ....................................................................................................................................... 47

3.3.9.

CONSULTA IMPRESSO NFE:................................................................................................................................ 49

3.3.10. CONSULTA IMPRESSO CARTA CORREO NFE: ................................................................................................... 50


4.

MDULO CTE ............................................................................................................................................ 52

4.1. OBSERVAES GERAIS ......................................................................................................................... 52


4.2. MTODO: 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. MTODO: GET ........................................................................................................................................ 64


4.3.1. CONSULTA PADRO ............................................................................................................................................ 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 IMPRESSO ........................................................................................................................................ 74

5.

MDULO MDFE ......................................................................................................................................... 75

5.1. OBSERVAES GERAIS ......................................................................................................................... 75


5.2. MTODO: 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. MTODO: GET ........................................................................................................................................ 84


5.3.1. CONSULTA PADRO ............................................................................................................................................ 84
5.3.2.

GETXML .............................................................................................................................................................. 86

5.3.3.

CONSULTA RETORNO .......................................................................................................................................... 87

5.3.4.

CONSULTA IMPRESSO ........................................................................................................................................ 89

5.3.5.

GETDAMDFE ....................................................................................................................................................... 91

Verso: 1.22
Atualizado em: 09/06/2015

MASTERSAF DFE
6.

INTEGRAO COM WEBSERVICE DF-E V3

MDULO RECEPTOR NFSE (SERVIO) .................................................................................................... 92

6.1. OBSERVAES GERAIS ......................................................................................................................... 92


6.2. MTODO: POST ........................................................................................................................................ 92
6.2.1. MARCARCONSULTADO: ....................................................................................................................................... 92
6.3. MTODO: GET ........................................................................................................................................ 94
6.3.1. CONSULTA PADRO ............................................................................................................................................ 94
7.

MDULO RECEPTOR NFE (MERCANTIL) ................................................................................................. 95

7.1. OBSERVAES GERAIS .......................................................................................................................... 95


7.2. MTODO: POST ...................................................................................................................................... 96
7.2.1. ENVIARRECEBIMENTO.......................................................................................................................................... 96
7.2.2.

ENVIAREVENTOMANIFESTACAO ........................................................................................................................... 98

7.2.3.

MARCARCONSULTADO: ..................................................................................................................................... 100

7.2.4.

MARCARIMPRESSO: ........................................................................................................................................... 101

7.3. MTODO: GET....................................................................................................................................... 103


7.3.1. CONSULTA PADRO .......................................................................................................................................... 103
7.3.2.

GETXML ............................................................................................................................................................ 104

7.3.3.

GETXMLCANCELAMENTO ................................................................................................................................... 106

7.3.4.

GETSTATUS....................................................................................................................................................... 107

7.3.5.

CONSULTA IMPRESSO ...................................................................................................................................... 109

8.

MDULO RECEPTOR CTE ....................................................................................................................... 110

8.1. OBSERVAES GERAIS ....................................................................................................................... 110


8.2. MTODO: POST .................................................................................................................................... 110
8.2.1. ENVIARRECEBIMENTO........................................................................................................................................ 110
8.2.2.

CONSULTARDOCFORNECEDOR .......................................................................................................................... 112

8.2.3.

RESGATARXMLFORNECEDOR ............................................................................................................................. 115

8.2.4.

MARCARCONSULTADO: ..................................................................................................................................... 117

8.3. MTODO: GET ...................................................................................................................................... 119


8.3.1. CONSULTA PADRO .......................................................................................................................................... 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. OBSERVAES GERAIS ...................................................................................................................... 125


10.2. UTILIZANDO A EXTENSO REST CLIENT DO FIREFOX ..................................................................... 126
Verso: 1.22
Atualizado em: 09/06/2015

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

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.

RELAO DE MUDANAS DE VERSES DO MANUAL ........................................................................ 130

13.

SUPORTE TCNICO ............................................................................................................................... 132

Verso: 1.22
Atualizado em: 09/06/2015

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

1. INTRODUO
O mdulo Webservice da Soluo MASTERSAF DFE V3 baseado em requisies REST. Utilizamos dois
tipos de requisies: POST e GET. Todas as requisies exigem um usurio e senha informados por Basic

Authentication.
As requisies do tipo POST exigem algum contedo (Request Body). atravs desse contedo que a
requisio ser processada.
Nas requisies do tipo GET no necessrio informar nenhum contedo, pois na prpria URL sero
passados os parmetros.

2. MDULO NFSE (SERVIO)


2.1. OBSERVAES GERAIS
Resumindo o processo, primeiramente enviado um pacote de dados; depois feita uma consulta
recebendo uma lista de ids e, ento por fim, marcam-se no sistema os ids consultados para que numa
prxima consulta eles no sejam retornados novamente.
Com isso basta realizar POST para enviar os pacotes e GET para consultar o resultado do
processamento.
2.2. MTODO: POST
2.2.1. EnviarPacote
2.2.1.1.

Introduo

Mtodo utilizado para enviar RPSs ao WebService.


2.2.1.2.

URL:

<host>:<port>/<webservice>/api/dfe

Verso: 1.22
Atualizado em: 09/06/2015

MASTERSAF DFE
2.2.1.3.

INTEGRAO COM WEBSERVICE DF-E V3

Exemplo URL:

http://localhost:8080/webservice/api/dfe (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/dfe (ambiente de homologao do SaaS)
2.2.1.4.

Layout

CAMPO

DESCRIO

action

Ao solicitada

txt_conteudo

CONTEDO
EnviarPacote

Contedo do RPS. Informar dados do RPS


conforme layout padro do produto.

OBRIG
Sim
Sim

*Outras tags informadas no sero utilizadas, portanto, no as informe.


2.2.1.5.

Permisses

Permisses conforme cadastro de usurios:


- NFS-e Integrador (ROLE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
2.2.1.6.

Cabealho

Detalhes que devem ser informados na requisio:


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 contedo o pipe ( | ). Para quebra de linha usa-se \n.

Verso: 1.22
Atualizado em: 09/06/2015

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Para enviar vrios RPSs voc deve concatenar as strings antes de colocar em txt_contedo (txt contedo
ter vrios "__rps__|versao=1(...)"), mas s pode existir um "__arquivo_fim__|". No caso de cancelamento o
procedimento o mesmo (vrios __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":"<descrio do erro>"}


Http status: 400, 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
2.2.2. Cancelar
2.2.2.1.

Introduo

Mtodo 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 (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/dfe (ambiente de homologao do SaaS)
2.2.2.4.

Layout

CAMPO

DESCRIO

action

Ao solicitada

Verso: 1.22
Atualizado em: 09/06/2015

CONTEDO OBRIG.
Cancelar

Sim

MASTERSAF DFE
txt_conteudo

INTEGRAO COM WEBSERVICE DF-E V3


Contedo do Cancelamento de RPS. Informar dados do
RPS conforme layout padro do produto.

Sim

*Outras tags informadas no sero utilizadas, portanto, no as informe.


2.2.2.5.

Permisses

Permisses conforme cadastro de usurios:


- NFS-e Integrador (ROLE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
2.2.2.6.

Cabealho

Detalhes que devem ser informados na requisio:


-

authentication utilizando o usurio 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 contedo 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 (Solicitao enviada com sucesso)
2.2.2.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Verso: 1.22
Atualizado em: 09/06/2015

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Http status: 400, 412, 500.


*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
2.2.3. MarcarConsultado:
2.2.3.1.

Introduo

Mtodo para indicar ao WebService que determinados documentos j foram consultados e no precisam
mais ser retornados na consulta (GET).
Deve ser utilizado depois do mtodo de consulta onde so listados os documentos para gerao de
retorno.
2.2.3.2.

URL:

<host>:<port>/<webservice>/api/dfe
2.2.3.3.

Exemplo URL:

http://localhost:8080/webservice/api/dfe (instalao in house)


Ou
https://ws.h.dfe.mastersaf.com.br/api/dfe (ambiente de homologao do SaaS)
2.2.3.4.

Layout

CAMPO

DESCRIO

action

Ao solicitada

ids

CONTEDO
MarcarConsultado

Listagem de ids dos processamentos a serem


marcados como consultados.

*Outras tags informadas no sero utilizadas, portanto, no as informe.


2.2.3.5.

Permisses

Permisses conforme cadastro de usurios:


- NFS-e Integrador (ROLE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
Verso: 1.22
Atualizado em: 09/06/2015

10

OBRIG.
Sim
Sim

MASTERSAF DFE
2.2.3.6.

INTEGRAO COM WEBSERVICE DF-E V3

Cabealho

Detalhes que devem ser informados na requisio:


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 (Solicitao enviada com sucesso)
2.2.3.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
2.2.4. ConsultarRpssAguardandoDownload:
2.2.4.1.

Introduo

Mtodo para consultar RPSs que esto com status de aguardando download no portal. Sero retornados
os arquivos que devem ser utilizados nos portais das prefeituras.
2.2.4.2.

URL:

url: <host>:<port>/<webservice>/api/dfe
Verso: 1.22
Atualizado em: 09/06/2015

11

MASTERSAF DFE
2.2.4.3.

INTEGRAO COM WEBSERVICE DF-E V3

Exemplo URL:

http://localhost:8080/webservice/api/dfe (instalao in house)


Ou
https://ws.h.dfe.mastersaf.com.br/api/dfe (ambiente de homologao do SaaS)
2.2.4.4.

Layout

CAMPO

DESCRIO

action

Ao solicitada

referencia

CONTEDO
ConsultarRpssAguardandoDownload

Informar referncia da empresa a


ser consultada.

"00910509000171_12345678"

OBRIG
Sim
Sim

*Outras tags informadas no sero utilizadas, portanto, no as informe.


2.2.4.5.

Permisses

Permisses conforme cadastro de usurios:


- NFS-e Integrador (ROLE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
2.2.4.6.

Cabealho

Detalhes que devem ser informados na requisio:


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
Verso: 1.22
Atualizado em: 09/06/2015

12

MASTERSAF DFE
2.2.4.8.

INTEGRAO COM WEBSERVICE DF-E V3

Retorno Sucesso

Response Body: {"formatoArquivo":"","body":"","result":"OK"}


Http status: 200 (Solicitao enviada com sucesso)
2.2.4.8.1. Layout Retorno
CAMPO

DESCRIO

formatoArquivo

Formato do arquivo que est sendo retornado: TXT ou XML

body

Contedo do arquivo.

result
Consultar arquivo de exemplo: nfse_response_post_consultar_rpss_aguardando_download.txt
2.2.4.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 400, 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
2.2.5. UploadRetornoPrefeitura:
2.2.5.1.

Introduo

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 (instalao in house)


Ou
https://ws.h.dfe.mastersaf.com.br/api/dfe (ambiente de homologao do SaaS)

Verso: 1.22
Atualizado em: 09/06/2015

13

MASTERSAF DFE
2.2.5.4.

INTEGRAO COM WEBSERVICE DF-E V3

Layout

CAMPO

DESCRIO

action

Ao solicitada

referencia

CONTEDO
UploadRetornoPrefeitura

Informar:

"00910509000171_12345678_SC_JOINVI

<CNPJ>_<IM>_<UF>_<MUNICIPIO

LLE#joinville - rps 3

>#<nome arquivo de retorno>.xml

arquivo_retorno_prefeitura_joinville.xml"

Contedo do arquivo recebido da


txt_conteudo

prefeitura para ser atualizado no


software.

*Outras tags informadas no sero utilizadas, portanto, no as informe.


2.2.5.5.

Permisses

Permisses conforme cadastro de usurios:


- NFS-e Integrador (ROLE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
2.2.5.6.

Cabealho

Detalhes que devem ser informados na requisio:


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 mtodo.
Exemplo de Request Body conforme arquivo de exemplo:
nfse_request_post_upload_retorno_prefeitura.txt

Verso: 1.22
Atualizado em: 09/06/2015

14

OBRIG
Sim
Sim

MASTERSAF DFE
2.2.5.8.

INTEGRAO COM WEBSERVICE DF-E V3

Retorno Sucesso

Response Body: {"result":"OK"}


Http status: 200 (Solicitao enviada com sucesso)
2.2.5.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 400, 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
2.2.6. Convertida:
2.2.6.1.

Introduo

Mtodo 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 (instalao in house)


Ou
https://ws.h.dfe.mastersaf.com.br/api/dfe/convertida (ambiente de homologao do SaaS)
2.2.6.4.

Layout

CAMPO

DESCRIO

txt_conteudo

Dados do RPS para consulta.

cnpjPrestador

CONTEDO
Lista de campos que serviro de filtro
para o RPS.

Atributo de txt_conteudo. CNPJ do


Atributo de txt_conteudo.

ador

Inscrio Municipal do Prestador.

numeroRps

Atributo de txt_conteudo. Numero

Verso: 1.22
Atualizado em: 09/06/2015

Sim
Sim

Prestador.

inscricaoPrest

OBRIG

Sim
Sim
15

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

do RPS.
Atributo de txt_conteudo. Srie do

serieRps

Sim

RPS.

*Outras tags informadas no sero utilizadas, portanto, no as informe.


2.2.6.5.

Permisses

Permisses conforme cadastro de usurios:


- NFS-e Integrador (ROLE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
2.2.6.6.

Cabealho

Detalhes que devem ser informados na requisio:


-

o usurio 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 mtodo.
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

DESCRIO

ids

Listagem dos IDs dos processamentos.

rpss

Listagem dos RPSs.

Verso: 1.22
Atualizado em: 09/06/2015

16

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Os campos numricos retornaro sem aspas, demais campos sero retornados entre

Consultar arquivo de exemplo: nfse_response_convertida.txt


2.2.6.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 400, 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
2.3. MTODO: GET
2.3.1. Consulta Padro
2.3.1.1.

Introduo

Mtodo para obter os retornos dos documentos enviados e a lista de documentos no consultados.
2.3.1.2.

URL:

<host>:<port>/<webservice>/api/dfe
2.3.1.3.

Filtro de Srie e Quantidade de Resultados (maxResults):

Pode ser informado os parmetros de Srie NF-e e MaxResults para realizar a busca.
Quando no informada quantidade no parmetro maxResults, ser considerada a quantidade de 50
(cinquenta) results para cada consulta.
2.3.1.4.

Exemplo URL:

http://localhost:8080/webservice/api/dfe (instalao in house)


Ou
https://ws.h.dfe.mastersaf.com.br/api/dfe (ambiente de homologao do SaaS)
http://localhost:8080/webservice/api/dfe?maxResults=100&serie=001 (instalao in house)
Ou
Verso: 1.22
Atualizado em: 09/06/2015

17

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

https://ws.h.dfe.mastersaf.com.br/api/dfe?maxResults=100&serie=001 (ambiente de homologao do


SaaS)
2.3.1.5.

Permisses

Permisses conforme cadastro de usurios:


- NFS-e Integrador (ROLE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
2.3.1.6.

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
2.3.1.7.

Envio

Nenhum dado alm do cabealho 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

DESCRIO
Contedo do retorno. Possui uma lista dos IDs dos

retorno

processamentos e uma listagens de seus respectivos RPSs.

ids

Listagem dos IDs dos processamentos.

rpss

Listagem dos RPSs.

No mtodo GET, o resultado dos campos numricos retornaro sem aspas, demais campos sero
.
Verso: 1.22
Atualizado em: 09/06/2015

18

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Consultar arquivo de exemplo: nfse_response_get.txt


2.3.1.9.

Retorno Erro

No h

3. MDULO NFE (MERCANTIL)


3.1. OBSERVAES GERAIS
Resumindo o processo, primeiramente enviado um pacote de dados; depois feita uma consulta
recebendo uma lista de ids e, ento por fim, marcam-se no sistema os ids consultados para que numa
prxima consulta eles no sejam retornados novamente.
Para todos os requests preciso usar basic authentication utilizando o usurio 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 padro
SEFAZ.
3.2. MTODO: POST
3.2.1. EnviarPacote:
3.2.1.1.

Introduo

Mtodo 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 (instalao in house)


Verso: 1.22
Atualizado em: 09/06/2015

19

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

ou
https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologao do SaaS)
3.2.1.4.

Layout

CAMPO

DESCRIO

CONTEDO

action

Ao solicitada

referencia

Nome do arquivo utilizado na integrao.

No

txt_conteudo

Grupo de informao da NF-e

Sim

EnviarPacote

Contedo do XML de NF-e. Informar dados do

xml

NF-e conforme layout padro da Receita Federal.

mastersaf
id_integrador

Informaes para contingncia ou parmetros


para filtro de impresso.
Nome do integrador responsvel pelo envio do
documento.

OBRIG.
Sim

Sim
No
No

*Outras tags informadas no sero utilizadas, portanto, no as informe.


3.2.1.5.

Permisses

Permisses conforme cadastro de usurios:


- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
3.2.1.6.

Cabealho

Detalhes que devem ser informados na requisio:


-

preciso usar basic authentication utilizando o usurio 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 mtodo.
Exemplo de Request Body conforme arquivo de exemplo: nfe_request_post_enviar_pacote_1.txt
Verso: 1.22
Atualizado em: 09/06/2015

20

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

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":"<descrio do erro>"}


Http status: 400, 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
3.2.2. Cancelar
3.2.2.1.

Introduo

Mtodo 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 (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologao do SaaS)
3.2.2.4.

Layout

CAMPO

DESCRIO

action

Ao solicitada

Sim

referencia

Nome do arquivo de integrao

No

txt_conteudo

Grupo de informaes de cancelamento.

Sim

Verso: 1.22
Atualizado em: 09/06/2015

CONTEDO

21

OBRIG.

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Contedo do Cancelamento de NF-e. Informar dados de

xml

Cancelamento da NF-e conforme layout padro do produto.

id_integrador

Nome do integrador responsvel pelo envio do documento.

Sim
No

*Outras tags informadas no sero utilizadas, portanto, no as informe.


3.2.2.5.

Permisses

Permisses conforme cadastro de usurios:


- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
3.2.2.6.

Cabealho

Detalhes que devem ser informados na requisio:


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 (Solicitao enviada com sucesso)
3.2.2.9.

Retorno Erro

Verso: 1.22
Atualizado em: 09/06/2015

22

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Response Body: {"result":"<descrio do erro>"}


Http status: 400, 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
3.2.3. Inutilizar
3.2.3.1.

Introduo

Mtodo para inutilizar numeraes de NF-es que ainda no foram utilizadas.


3.2.3.2.

URL:

<host>:<port>/<webservice>/api/nfe
3.2.3.3.

Exemplo URL:

http://localhost:8080/webservice/api/nfe (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologao do SaaS)
3.2.3.4.

Layout

CAMPO

DESCRIO

CONTEDO

action

Ao solicitada

Sim

referencia

Nome do arquivo de integrao

No

txt_conteudo

Grupo de informaes de inutilizao.

Sim

Contedo da Inutilizao de NF-e. Informar

xml

dados conforme layout padro do produto.

id_integrador

Nome do integrador responsvel pelo envio


do documento.

*Outras tags informadas no sero utilizadas, portanto, no as informe.


3.2.3.5.

Permisses

Permisses conforme cadastro de usurios:


- NF-e Integrador (ROLE_NFE_INTEGRADOR)
Verso: 1.22
Atualizado em: 09/06/2015

23

OBRIG.

Sim
No

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

- Administrar o sistema (ROLE_SUPER_ADMIN)


* O usurio informado na requisio deve possuir ao menos uma destas permisses.
3.2.3.6.

Cabealho

Detalhes que devem ser informados na requisio:


-

dos os requests preciso usar basic authentication utilizando o usurio 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 (Solicitao enviada com sucesso)
3.2.3.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 400, 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
3.2.4. EnviarCartaCorrecaoNfe
3.2.4.1.

Introduo

Mtodo para emitir cartas de correo para NF-es j autorizadas.

Verso: 1.22
Atualizado em: 09/06/2015

24

MASTERSAF DFE
3.2.4.2.

INTEGRAO COM WEBSERVICE DF-E V3

URL:

<host>:<port>/<webservice>/api/nfe
3.2.4.3.

Exemplo URL:

http://localhost:8080/webservice/api/nfe (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologao do SaaS)
3.2.4.4.

Layout

CAMPO

DESCRIO

CONTEDO

OBRIG

action

Ao solicitada

Sim

referencia

Nome do arquivo de integrao

No

txt_conteudo

Grupo de informaes de carta de correo.

Sim

Contedo da Carta de Correo de NF-e.


xml

Informar dados conforme layout padro do

Sim

produto.
id_integrador

Nome do integrador responsvel pelo envio do


documento.

*Outras tags informadas no sero utilizadas, portanto, no as informe.


3.2.4.5.

Permisses

Permisses conforme cadastro de usurios:


- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
3.2.4.6.

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
Verso: 1.22
Atualizado em: 09/06/2015

25

No

MASTERSAF DFE
-

3.2.4.7.

Envio

INTEGRAO COM WEBSERVICE DF-E V3

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 (Solicitao enviada com sucesso)
3.2.4.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 400, 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
3.2.5. MarcarConsultado
3.2.5.1.

Introduo

Mtodo para indicar ao WebService que determinados documentos j foram consultados e no precisam
mais ser retornados na consulta (GET).
Deve ser utilizado depois do mtodo de consulta onde so listados os documentos para gerao de
retorno.
3.2.5.2.

URL:

<host>:<port>/<webservice>/api/nfe
3.2.5.3.

Exemplo URL:

http://localhost:8080/webservice/api/nfe (instalao in house)


Verso: 1.22
Atualizado em: 09/06/2015

26

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

ou
https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologao do SaaS)
3.2.5.4.

Layout

CAMPO

DESCRIO

action

Ao solicitada

CONTEDO
MarcarConsultado

Listagem de ids dos processamentos a serem

ids

marcados como consultados.

id_integrador

Nome do integrador responsvel pelo envio


do documento.

OBRIG.
Sim
Sim
No

*Outras tags informadas no sero utilizadas, portanto, no as informe.


3.2.5.5.

Permisses

Permisses conforme cadastro de usurios:


- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
3.2.5.6.

Cabealho

Detalhes que devem ser informados na requisio:


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"}


Verso: 1.22
Atualizado em: 09/06/2015

27

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Http status: 200 (Solicitao enviada com sucesso)


3.2.5.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
3.2.6. MarcarImpresso
3.2.6.1.

Introduo

Mtodo para indicar ao WebService que determinados documentos j foram impressos e no precisam
mais ser retornados na consulta (GET).
Deve ser utilizado depois do mtodo de consulta onde so listados os documentos para gerao de
retorno.
3.2.6.2.

URL:

<host>:<port>/<webservice>/api/nfe
3.2.6.3.

Exemplo URL:

http://localhost:8080/webservice/api/nfe (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologao do SaaS)
3.2.6.4.

Layout

CAMPO

DESCRIO

CONTEDO

action

Ao solicitada

Sim

ids

Grupo de informaes para marcar como impresso.

Sim

idProcessamento

Id do processamento a ser marcado.

Sim

idNota

Id da nota a ser marcada.

Sim

*Outras tags informadas no sero utilizadas, portanto, no as informe.

Verso: 1.22
Atualizado em: 09/06/2015

28

OBRIG

MASTERSAF DFE
3.2.6.5.

INTEGRAO COM WEBSERVICE DF-E V3

Permisses

Permisses conforme cadastro de usurios:


- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
3.2.6.6.

Cabealho

Detalhes que devem ser informados na requisio:


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 (Solicitao enviada com sucesso)
3.2.6.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
3.2.7. MarcarCartaCorrecaoImpresso
3.2.7.1.

Introduo

Verso: 1.22
Atualizado em: 09/06/2015

29

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Mtodo para indicar ao WebService que determinados Cartas de Correo j foram impressos e no
precisam mais ser retornados na consulta (GET).
Deve ser utilizado depois do mtodo de consulta onde so listados os documentos para gerao de
retorno.
3.2.7.2.

URL:

<host>:<port>/<webservice>/api/nfe
3.2.7.3.

Exemplo URL:

http://localhost:8080/webservice/api/nfe (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologao do SaaS)
3.2.7.4.

Layout

CAMPO

DESCRIO

Action

Ao solicitada

CONTEDO
MarcarCartaCorrecaoImpresso

Grupo de informaes para marcar

Ids

como impresso.

OBRIG
Sim
Sim

idProcessamento

Id do processamento a ser marcado.

Sim

idNota

Id da CCe a ser marcada.

Sim

*Outras tags informadas no sero utilizadas, portanto, no as informe.


3.2.7.5.

Permisses

Permisses conforme cadastro de usurios:


- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
3.2.7.6.

Cabealho

Detalhes que devem ser informados na requisio:

Verso: 1.22
Atualizado em: 09/06/2015

30

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

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 (Solicitao enviada com sucesso)
3.2.7.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
3.2.8. ReimpressaoDanfe
3.2.8.1.

Introduo

Mtodo para solicitar reimpresso 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 (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologao do SaaS)
Verso: 1.22
Atualizado em: 09/06/2015

31

MASTERSAF DFE
3.2.8.4.

INTEGRAO COM WEBSERVICE DF-E V3

Layout

CAMPO

DESCRIO

CONTEDO

action

Ao solicitada

txt_conteudo

Grupo de informaes de reimpresso.

ReimpressaoDanfe

Contedo da solicitao de Reimpresso de NF-e.

xml

Informar dados conforme layout padro do produto.

OBRIG
Sim
Sim
Sim

*Outras tags informadas no sero utilizadas, portanto, no as informe.


3.2.8.5.

Permisses

Permisses conforme cadastro de usurios:


- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
3.2.8.6.

Cabealho

Detalhes que devem ser informados na requisio:


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"}


Verso: 1.22
Atualizado em: 09/06/2015

32

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Http status: 200 (Solicitao enviada com sucesso)


3.2.8.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 400, 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
3.2.9. Consultar Cadastro
3.2.9.1.

Introduo

Mtodo 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 (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologao do SaaS)
3.2.9.4.

Layout

CAMPO

DESCRIO

CONTEDO

OBRIG

action

Ao solicitada

Sim

referencia

Nome do arquivo utilizado na integrao.

No

txt_conteudo Grupo de informao da consulta.


xml

Sim

Contedo da Consulta do Cadastro conforme layout padro

Sim

do produto.

*Outras tags informadas no sero utilizadas, portanto, no as informe.


3.2.9.4.1.

Detalhamento campo XML

CAMPO

DESCRIO

CONTEDO

TIPO

TAMANHO

Verso do Layout

2.00

Caractere 4

--consulta_cadastro_ini-versao
Verso: 1.22
Atualizado em: 09/06/2015

33

MASTERSAF DFE
CNPJ
IE
UF_pesquisa
IE_pesquisa

INTEGRAO COM WEBSERVICE DF-E V3


CNPJ da empresa.

Identificao da empresa Caractere 14

Inscrio Estadual da

para o qual ser

empresa.

retornado a consulta.

UF qual se destina a

Caractere
Caractere

consulta.
Inscrio Estadual a ser
consultada.

Somente um dos campos

CNPJ_pesquisa

CNPJ a ser consultado.

deve ser preenchido.

CPF_pesquisa

CPF a ser consultado.

Caractere

0-14
2
0-14

Caractere 14
Caractere 11

--consulta_cadastro_fim---arquivo_fim-3.2.9.5.

Permisses

Permisses conforme cadastro de usurios:


- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
3.2.9.6.

Cabealho

Detalhes que devem ser informados na requisio:


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 mtodo.
3.2.9.8.

Retorno Sucesso

Response Body: {"result":"OK"}


Http status: 202

Verso: 1.22
Atualizado em: 09/06/2015

34

MASTERSAF DFE
3.2.9.9.

INTEGRAO COM WEBSERVICE DF-E V3

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 400, 412, 500.
3.3. MTODO: GET
3.3.1. Consulta Padro:
3.3.1.1.

Introduo

Mtodo para obter os retornos dos documentos enviados, lista de documentos no consultados, dados
de lotes inutilizados, dados de cartas de correo 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 parmetro, ser considerada a quantidade mxima de results para
cada lista e grupo de retorno (impressao[], impressaoCce[], retorno{...}).
Quando no informada quantidade no parmetro, 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 (instalao in house)


Ou
https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologao do SaaS)
http://localhost:8080/webservice/api/nfe?maxResults=100 (instalao in house)
Ou
Verso: 1.22
Atualizado em: 09/06/2015

35

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

https://ws.h.dfe.mastersaf.com.br/api/nfe?maxResults=100 (ambiente de homologao do SaaS)


3.3.1.5.

Permisses

Permisses conforme cadastro de usurios:


- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
3.3.1.6.

Cabealho

Detalhes que devem ser informados na requisio:


-

urio e

a senha fornecidos.
3.3.1.7.

Envio

Nenhum dado alm do cabealho dever ser informado.


3.3.1.8.

Retorno Sucesso

Response Body:
{
"impressao": [],
"impressaoCCe": [],
"retorno": {
"loteCartaCorrecao": [],
"consultaCadastro": [],
"nfes": [],
"ids": [],
"loteInutilizado": []
}
} Http status: 200

Verso: 1.22
Atualizado em: 09/06/2015

36

MASTERSAF DFE
3.3.1.8.1.

INTEGRAO COM WEBSERVICE DF-E V3

Layout Retorno

CAMPO

DESCRIO

Impressao

Lista documentos para impresso.

impressaoCce

Lista documentos de Carta de Correo para impresso.

idProcessamento

processamento.

params
retorno

Grupo de informaes para gerao dos arquivos de retorno.


Listagem dos IDs dos processamentos que constam

ids

como no consultados.
Atributo de

nfes

Listagem dos retornos das NF-es que foram processadas

pelo software.

loteCartaCorrecao

Listagem dos retornos das Cartas de Correo enviadas.

loteInutilizado

Inutilizaes enviadas.

consultaCadastro
Detalhamento de campos especficos do Layout Retorno
CAMPO

DESCRIO
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 impresso de DANFE (Autorizada ou Cancelada).
Para funcionamento da gerao do link do DANFE, o preenchimento do campo URL
de acesso ao portal da tela Administrao do Sistema > Extrato do Sistema torna-se

nfes.nota.urlDanfePortal

obrigatrio.
Para a visualizao do DANFE o usurio dever ter a permisso 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

Verso: 1.22
Atualizado em: 09/06/2015

37

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

No h
3.3.2. GetXml
3.3.2.1.

Introduo

Mtodo 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
(instalao in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/nfe/<chave nfe>/getXml
(ambiente de homologao do SaaS)
3.3.2.4.

Permisses

Permisses conforme cadastro de usurios:


- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
3.3.2.5.

Cabealho

Detalhes que devem ser informados na requisio:


-

preciso usar basic authentication utilizando o usurio e

a senha fornecidos.
-

-8859-

correta.
Verso: 1.22
Atualizado em: 09/06/2015

38

Para o xml retornar com a codificao

MASTERSAF DFE
3.3.2.6.

INTEGRAO COM WEBSERVICE DF-E V3

Envio

Nenhum dado alm do cabealho 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":"<descrio do erro>"}


Http status: 203, 404, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
3.3.3. GetXmlCancelamento
3.3.3.1.

Introduo

Mtodo 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
(instalao in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/nfe/<chave nfe>/getXmlCancelamento
(ambiente de homologao do SaaS)
3.3.3.4.

Permisses

Verso: 1.22
Atualizado em: 09/06/2015

39

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Permisses conforme cadastro de usurios:


- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
3.3.3.5.

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
-

-8859-

Para o xml retornar com a codificao

correta.
3.3.3.6.

Envio

Nenhum dado alm do cabealho 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":"<descrio do erro>"}


Http status: 203, 404, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
3.3.4. GetDanfe
3.3.4.1.

Introduo

Mtodo para obter o DANFE da respectiva chave de NF-e.


Verso: 1.22
Atualizado em: 09/06/2015

40

MASTERSAF DFE
3.3.4.2.

INTEGRAO COM WEBSERVICE DF-E V3

URL:

<host>:<port>/<webservice>/api/nfe/<chave nfe>/getDanfe
3.3.4.3.

Exemplo URL:

http://localhost:8080/webservice/api/nfe/<chave nfe>/getDanfe
(instalao in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/nfe/<chave nfe>/getDanfe
(ambiente de homologao do SaaS)
3.3.4.4.

Permisses

Permisses conforme cadastro de usurios:


- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
3.3.4.5.

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
3.3.4.6.

Envio

Nenhum dado alm do cabealho 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
Verso: 1.22
Atualizado em: 09/06/2015

41

MASTERSAF DFE
3.3.4.8.

INTEGRAO COM WEBSERVICE DF-E V3

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 203, 404, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
3.3.5. GetStatus
3.3.5.1.

Introduo

Mtodo para obter o Status (Cdigo-Descrio) 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


(instalao in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/nfe/<chave nfe>/ getStatus
(ambiente de homologao do SaaS)
3.3.5.4.

Permisses

Permisses conforme cadastro de usurios:


- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
3.3.5.5.

Cabealho

Detalhes que devem ser informados na requisio:


Verso: 1.22
Atualizado em: 09/06/2015

42

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

requests preciso usar basic authentication utilizando o usurio e

a senha fornecidos.
3.3.5.6.

Envio

Nenhum dado alm do cabealho 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

DESCRIO

retorno

Grupo de informaes para gerao dos arquivos de retorno.

ids

no consultados.
-es que foram processadas

nfes

pelo software.

loteCartaCorrecao
loteInutilizado
3.3.5.9.

nutilizaes enviadas.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 203, 404, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
3.3.6. GetStatus (com parmetros)
3.3.6.1.

Introduo

Mtodo para obter o Status (Cdigo-Descrio) de NF-e apartir de um conjunto de filtros.


3.3.6.2.

URL:

Verso: 1.22
Atualizado em: 09/06/2015

43

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

<host>:<port>/<webservice>/api/nfe/getStatus
3.3.6.3.

Filtro de CNPJ Emissor, Nmero da NF-e e Srie da NF-e:

necessrio informar os parmetros de CNPJ Emissor, Nmero NF-e e Srie NF-e para realizar a busca.
Todos os parmetros so obrigatrios.
3.3.6.4.

Exemplo URL:

http://localhost:8080/webservice/api/nfe/getStatus?cnpjEmissor=1234567890&numeroNfe=1000&ser
ie=730
(instalao in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/nfe/getStatus?cnpjEmissor=1234567890&numeroNfe=1000&se
rie=730
(ambiente de homologao do SaaS)
3.3.6.5.

Permisses

Permisses conforme cadastro de usurios:


- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
3.3.6.6.

Cabealho

Detalhes que devem ser informados na requisio:


-

o usurio e

a senha fornecidos.
3.3.6.7.

Envio

Nenhum dado alm do cabealho dever ser informado.

Verso: 1.22
Atualizado em: 09/06/2015

44

MASTERSAF DFE
3.3.6.8.

INTEGRAO COM WEBSERVICE DF-E V3

Retorno Sucesso

Response Body: {retorno":{"loteCartaCorrecao":[],"nfes":[],"ids":[],"loteInutilizado":[]}}


Http status: 200
3.3.6.9.

Layout Retorno

CAMPO

DESCRIO

retorno

Grupo de informaes para gerao dos arquivos de retorno.

ids

no consultados.
-es que foram processadas

nfes

pelo software.

loteCartaCorrecao
loteInutilizado
3.3.6.10. Retorno Erro
Response Body: {"result":"<descrio do erro>"}
Http status: 203, 404, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
3.3.7. Consulta Retorno:
3.3.7.1.

Introduo

Mtodo para obter os retornos dos documentos enviados, lista de documentos no consultados, dados
de lotes inutilizados e dados de cartas de correo.
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=

Verso: 1.22
Atualizado em: 09/06/2015

45

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Quando no informada quantidade no parmetro, ser considerada a quantidade de 50 (cinquenta)


results para cada consulta.
3.3.7.4.

Filtro de Srie

Para filtrar a consulta pela srie, a mesma dever ser enviada na URL. Se houver mais de uma, separlas por vrgula.
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 (instalao in house)


Ou
https://ws.h.dfe.mastersaf.com.br/api/nfe/getRetorno (ambiente de homologao do SaaS)
http://localhost:8080/webservice/api/nfe/getRetorno?maxResults=100 (instalao in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/nfe/getRetorno?maxResults=100 (ambiente de homologao do
SaaS)
3.3.7.7.

Permisses

Permisses conforme cadastro de usurios:


- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
Verso: 1.22
Atualizado em: 09/06/2015

46

MASTERSAF DFE
3.3.7.8.

INTEGRAO COM WEBSERVICE DF-E V3

Cabealho

Detalhes que devem ser informados na requisio:


-

utilizando o usurio e

a senha fornecidos.
3.3.7.9.

Envio

Nenhum dado alm do cabealho 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

DESCRIO

retorno

Grupo de informaes para gerao dos arquivos de retorno.

ids

no consultados.
-es que foram processadas

nfes

pelo software.

loteCartaCorrecao
loteInutilizado
Consultar arquivo de exemplo: nfe_response_getRetorno.txt
3.3.7.11.

Retorno Erro

No h
3.3.8. Consulta Impresso:
3.3.8.1.

Introduo

Verso: 1.22
Atualizado em: 09/06/2015

47

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Mtodo 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 (instalao in house)


Ou
https://ws.h.dfe.mastersaf.com.br/api/nfe/getImpressao (ambiente de homologao do SaaS)
3.3.8.4.

Permisses

Permisses conforme cadastro de usurios:


- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
3.3.8.5.

Cabealho

Detalhes que devem ser informados na requisio:


-

preciso usar basic authentication utilizando o usurio e

a senha fornecidos.
3.3.8.6.

Envio

Nenhum dado alm do cabealho dever ser informado.


3.3.8.7.

Retorno Sucesso

Response Body: {"impressao":[], "impressaoCCe":[]}


Http status: 200

Verso: 1.22
Atualizado em: 09/06/2015

48

MASTERSAF DFE
3.3.8.7.1.

INTEGRAO COM WEBSERVICE DF-E V3

Layout Retorno

CAMPO

DESCRIO

impressao

Lista documentos para impresso.

impressaoCCe

Lista de eventos de carta de correo para impresso.

idProcessamento
params
Consultar arquivo de exemplo: nfe_response_getImpressao.txt
3.3.8.8.

Retorno Erro

No h
3.3.9. Consulta Impresso NFe:
3.3.9.1.

Introduo

Mtodo para obter apenas os retornos dos documentos de NF-e que devem ser enviados para o Printer
imprimir. Aps o retorno, o sistema marca os documentos como
no so mais retornados pelo mtodo.
3.3.9.2.

URL:

<host>:<port>/<webservice>/api/nfe/getImpressaoNfe
3.3.9.3.

Exemplo URL:

http://localhost:8080/webservice/api/nfe/getImpressaoNfe (instalao in house)


Ou
https://ws.h.dfe.mastersaf.com.br/api/nfe/getImpressaoNfe(ambiente de homologao do SaaS)
3.3.9.4.

Permisses

Permisses conforme cadastro de usurios:


- NF-e Integrador (ROLE_NFE_INTEGRADOR)
Verso: 1.22
Atualizado em: 09/06/2015

49

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

- Administrar o sistema (ROLE_SUPER_ADMIN)


* O usurio informado na requisio deve possuir ao menos uma destas permisses.
3.3.9.5.

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
3.3.9.6.

Envio

Nenhum dado alm do cabealho dever ser informado.


3.3.9.7.

Retorno Sucesso

Response Body: {"impressao":[]}


Http status: 200
3.3.9.7.1.

Layout Retorno

CAMPO

DESCRIO

impressao

Lista documentos para impresso.

idProcessamento
params
Consultar arquivo de exemplo: nfe_response_getImpressaoNfe.txt
3.3.9.8.

Retorno Erro

No h
3.3.10. Consulta Impresso Carta Correo NFe:
3.3.10.1.

Introduo

Verso: 1.22
Atualizado em: 09/06/2015

50

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Mtodo 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 (instalao in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/nfe/getImpressaoCcNfe(ambiente de homologao do SaaS)
3.3.10.4. Permisses
Permisses conforme cadastro de usurios:
- NF-e Integrador (ROLE_NFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
3.3.10.5. Cabealho
Detalhes que devem ser informados na requisio:
-

usar basic authentication utilizando o usurio e

a senha fornecidos.
3.3.10.6. Envio
Nenhum dado alm do cabealho dever ser informado.
3.3.10.7.

Retorno Sucesso

Response Body: {"impressao":[]}


Http status: 200
Verso: 1.22
Atualizado em: 09/06/2015

51

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

3.3.10.7.1. Layout Retorno


CAMPO

DESCRIO

impressaoCCe

Lista de eventos de carta de correo para impresso.

idProcessamento
params
Consultar arquivo de exemplo: nfe_response_getImpressaoCcNfe.txt
3.3.10.8. Retorno Erro
No h

4. MDULO CTE
4.1. OBSERVAES GERAIS
Resumindo o processo, primeiramente enviado um pacote de dados; depois feita uma consulta
recebendo uma lista de ids e, ento por fim, marcam-se no sistema os ids consultados para que numa
prxima consulta eles no sejam retornados novamente, tambm so retornados os CT-es para
impresso via printer.
Para todos os requests preciso usar basic authentication utilizando o usurio 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 contedo o pipe ( | ). Para quebra de linha usa-se \n.
Para enviar vrios CT-es voc deve concatenar as strings antes de colocar em txt_contedo (txt contedo
ter vrios "{"config": " .. ", "xml" : "..."} separando-os por vrgula. No caso de cancelamento e
inutilizao o procedimento o mesmo.
4.2. MTODO: POST

Verso: 1.22
Atualizado em: 09/06/2015

52

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

4.2.1. EnviarPacote:
4.2.1.1.

Introduo

Mtodo 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 (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologao do SaaS)
4.2.1.4.

Layout

CAMPO

DESCRIO

action

Ao solicitada

Sim

referencia

Nome do arquivo utilizado na integrao.

No

txt_conteudo

Grupo de informaes do CT-e

Sim

xml
config

CONTEDO

Contedo do XML de CT-e. Informar dados conforme


layout padro da Receita Federal.
Configuraes.

Permisses

Permisses conforme cadastro de usurios:


- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
4.2.1.6.

Cabealho

Verso: 1.22
Atualizado em: 09/06/2015

Sim
Sim

*Outras tags informadas no sero utilizadas, portanto, no as informe.


4.2.1.5.

OBRIG

53

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Detalhes que devem ser informados na requisio:


a senha fornecidos.
-

4.2.1.7.

Envio

application/json

O corpo do POST (request body) deve ser um json contendo todos os campos do layout do mtodo.
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":"<descrio do erro>"}


Http status: 400, 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
4.2.2. Cancelar
4.2.2.1.

Introduo

Mtodo 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 (instalao in house)


ou
Verso: 1.22
Atualizado em: 09/06/2015

54

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologao do SaaS)


4.2.2.4.

Layout

CAMPO

DESCRIO

CONTEDO

action

Ao solicitada

Sim

referencia

Nome do arquivo de integrao

No

txt_conteudo

Grupo de informaes de cancelamento.

Sim

Contedo do Cancelamento de CT-e. Informar dados

xml

conforme layout padro da Receita Federal.

config

Configuraes.

OBRIG.

Sim
Sim

*Outras tags informadas no sero utilizadas, portanto, no as informe.


4.2.2.5.

Permisses

Permisses conforme cadastro de usurios:


- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
4.2.2.6.

Cabealho

Detalhes que devem ser informados na requisio:


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

Verso: 1.22
Atualizado em: 09/06/2015

55

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Response Body: {"result":"OK"}


Http status: 200 (Solicitao enviada com sucesso)
4.2.2.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 400, 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
4.2.3. EnviarCartaCorrecaoCte
4.2.3.1.

Introduo

Mtodo para emitir cartas de correo 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 (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologao do SaaS)
4.2.3.4.

Layout

CAMPO

DESCRIO

CONTEDO

action

Ao solicitada

Sim

referencia

Nome do arquivo de integrao

No

txt_conteudo

Grupo de informaes de carta de correo.

Sim

*Outras tags informadas no sero utilizadas, portanto, no as informe.


4.2.3.5.

Permisses

Permisses conforme cadastro de usurios:

Verso: 1.22
Atualizado em: 09/06/2015

56

OBRIG

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

- NF-e Integrador (ROLE_CTE_INTEGRADOR)


- Administrar o sistema (ROLE_SUPER_ADMIN)
- CT-e Carta Correo (ROLE_CTE_CARTA_CORRECAO)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
4.2.3.6.

Cabealho

Detalhes que devem ser informados na requisio:


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 (Solicitao enviada com sucesso)
4.2.3.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 400, 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
4.2.4. Inutilizar
4.2.4.1.

Introduo

Verso: 1.22
Atualizado em: 09/06/2015

57

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Mtodo para inutilizar numeraes de CT-es que ainda no foram utilizadas.


4.2.4.2.

URL:

<host>:<port>/<webservice>/api/cte
4.2.4.3.

Exemplo URL:

http://localhost:8080/webservice/api/cte (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologao do SaaS)
4.2.4.4.

Layout

CAMPO

DESCRIO

CONTEDO

action

Ao solicitada

Sim

referencia

Nome do arquivo de integrao

No

txt_conteudo

Grupo de informaes de inutilizao.

Sim

Contedo da Inutilizao de CT-e. Informar dados

xml

conforme layout padro da Receita Federal.

config

Configuraes.

Permisses

Permisses conforme cadastro de usurios:


- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
4.2.4.6.

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
Verso: 1.22
Atualizado em: 09/06/2015

Sim
Sim

*Outras tags informadas no sero utilizadas, portanto, no as informe.


4.2.4.5.

OBRIG.

58

MASTERSAF DFE
-

4.2.4.7.

Envio

INTEGRAO COM WEBSERVICE DF-E V3

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 (Solicitao enviada com sucesso)
4.2.4.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 400, 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
4.2.5. MarcarConsultado
4.2.5.1.

Introduo

Mtodo para indicar ao WebService que determinados documentos j foram consultados e no precisam
mais ser retornados na consulta (GET).
Deve ser utilizado depois do mtodo de consulta onde so listados os documentos para gerao de
retorno.
4.2.5.2.

URL:

<host>:<port>/<webservice>/api/cte
4.2.5.3.

Exemplo URL:

http://localhost:8080/webservice/api/cte (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologao do SaaS)
Verso: 1.22
Atualizado em: 09/06/2015

59

MASTERSAF DFE
4.2.5.4.

INTEGRAO COM WEBSERVICE DF-E V3

Layout

CAMPO DESCRIO
action
ids

CONTEDO

Ao solicitada

OBRIG
Sim

Listagem de ids dos processamentos a serem marcados


como consultados.

Sim

*Outras tags informadas no sero utilizadas, portanto, no as informe.


4.2.5.5.

Permisses

Permisses conforme cadastro de usurios:


- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
4.2.5.6.

Cabealho

Detalhes que devem ser informados na requisio:


-

odos os requests preciso usar basic authentication utilizando o usurio 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 (Solicitao enviada com sucesso)
4.2.5.9.

Retorno Erro

Verso: 1.22
Atualizado em: 09/06/2015

60

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Response Body: {"result":"<descrio do erro>"}


Http status: 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
4.2.6. MarcarImpresso
4.2.6.1.

Introduo

Mtodo para indicar ao WebService que determinados documentos j foram impressos e no precisam
mais ser retornados na consulta (GET).
Deve ser utilizado depois do mtodo de consulta onde so listados os documentos para gerao de
retorno.
4.2.6.2.

URL:

<host>:<port>/<webservice>/api/cte
4.2.6.3.

Exemplo URL:

http://localhost:8080/webservice/api/cte (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologao do SaaS)
4.2.6.4.

Layout

CAMPO

DESCRIO

CONTEDO

action

Ao solicitada

Sim

ids

Grupo de informaes para marcar como impresso.

Sim

idProcessamento

Id do processamento a ser marcado.

Sim

idNota

Id da nota a ser marcada.

Sim

*Outras tags informadas no sero utilizadas, portanto, no as informe.


4.2.6.5.

Permisses

Permisses conforme cadastro de usurios:


- CT-e Integrador (ROLE_CTE_INTEGRADOR)
Verso: 1.22
Atualizado em: 09/06/2015

61

OBRIG

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

- Administrar o sistema (ROLE_SUPER_ADMIN)


* O usurio informado na requisio deve possuir ao menos uma destas permisses.
4.2.6.6.

Cabealho

Detalhes que devem ser informados na requisio:


-

utilizando o usurio 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 (Solicitao enviada com sucesso)
4.2.6.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
4.2.7. MarcarCartaCorrecaoImpresso
4.2.7.1.

Introduo

Mtodo para indicar ao WebService que determinadas Cartas de Correo j foram impressos e no
precisam mais ser retornados na consulta (GET).
Deve ser utilizado depois do mtodo de consulta onde so listados os documentos para gerao de
retorno.
Verso: 1.22
Atualizado em: 09/06/2015

62

MASTERSAF DFE
4.2.7.2.

INTEGRAO COM WEBSERVICE DF-E V3

URL:

<host>:<port>/<webservice>/api/cte
4.2.7.3.

Exemplo URL:

http://localhost:8080/webservice/api/cte (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologao do SaaS)
4.2.7.4.

Layout

CAMPO

DESCRIO

action

Ao solicitada

CONTEDO
CartaCorrecaoImpresso

Grupo de informaes para marcar

ids

como impresso.

Sim
Sim

idProcessamento

Id do processamento a ser marcado.

Sim

idNota

Id da CCe a ser marcada.

Sim

*Outras tags informadas no sero utilizadas, portanto, no as informe.


4.2.7.5.

Permisses

Permisses conforme cadastro de usurios:


- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
4.2.7.6.

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
-

OBRIG

Verso: 1.22
Atualizado em: 09/06/2015

63

MASTERSAF DFE
4.2.7.7.

INTEGRAO COM WEBSERVICE DF-E V3

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 (Solicitao enviada com sucesso)
4.2.7.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
4.3. MTODO: GET
4.3.1. Consulta Padro
4.3.1.1.

Introduo

Mtodo para obter os retornos dos documentos enviados, lista de documentos no 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 parmetro, ser considerada a quantidade mxima de results para
cada lista e grupo de retorno (impressao[], retorno{...}).
Verso: 1.22
Atualizado em: 09/06/2015

64

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Quando no informada quantidade no parmetro, 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 (instalao in house)


Ou
https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologao do SaaS)
http://localhost:8080/webservice/api/cte?maxResults=100 (instalao in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/cte?maxResults=100 (ambiente de homologao do SaaS)
4.3.1.5.

Permisses

Permisses conforme cadastro de usurios:


- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
4.3.1.6.

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
4.3.1.7.

Envio

Nenhum dado alm do cabealho dever ser informado.


4.3.1.8.

Retorno Sucesso

Response Body:
{"impressao":[],"retorno":{"loteCartaCorrecao":[],"nfes":[],"ids":[],"loteInutilizado":[]}}
Verso: 1.22
Atualizado em: 09/06/2015

65

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Http status: 200


4.3.1.8.1.

Layout Retorno

CAMPO

DESCRIO

impressao

Lista documentos para impresso.

id
nota

Atribu

retorno

Grupo de informaes para gerao dos arquivos de retorno.


tam como no

ids

consultados.
CT-es que foram processadas pelo

ctes

software.

loteInutilizado
Consultar arquivo de exemplo: cte_response_get.txt
4.3.1.9.

Retorno Erro

No h
4.3.2. GetXml
4.3.2.1.

Introduo

Mtodo 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
(instalao in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/cte/<chave cte>/getXml
Verso: 1.22
Atualizado em: 09/06/2015

66

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

(ambiente de homologao do SaaS)


4.3.2.4.

Permisses

Permisses conforme cadastro de usurios:


- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
4.3.2.5.

Cabealho

Detalhes que devem ser informados na requisio:


-

usurio e

a senha fornecidos.
-

-8859-

Para o xml retornar com a codificao

correta.
4.3.2.6.

Envio

Nenhum dado alm do cabealho 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":"<descrio do erro>"}


Http status: 203, 404, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.

Verso: 1.22
Atualizado em: 09/06/2015

67

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

4.3.3. GetXmlCancelamento
4.3.3.1.

Introduo

Mtodo 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
(instalao in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/cte/<chave cte>/getXmlCancelamento
(ambiente de homologao do SaaS)
4.3.3.4.

Permisses

Permisses conforme cadastro de usurios:


- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
4.3.3.5.

Cabealho

Detalhes que devem ser informados na requisio:


-

odos os requests preciso usar basic authentication utilizando o usurio e

a senha fornecidos.
-

-8859-

correta.
4.3.3.6.

Envio

Verso: 1.22
Atualizado em: 09/06/2015

68

Para o xml retornar com a codificao

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Nenhum dado alm do cabealho 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":"<descrio do erro>"}


Http status: 203, 404, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
4.3.4. GetDacte
4.3.4.1.

Introduo

Mtodo 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
(instalao in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/cte/<chave cte>/getDacte
(ambiente de homologao do SaaS)
4.3.4.4.

Permisses

Permisses conforme cadastro de usurios:


Verso: 1.22
Atualizado em: 09/06/2015

69

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

- CT-e Integrador (ROLE_CTE_INTEGRADOR)


- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
4.3.4.5.

Cabealho

Detalhes que devem ser informados na requisio:


-

todos os requests preciso usar basic authentication utilizando o usurio e

a senha fornecidos.
4.3.4.6.

Envio

Nenhum dado alm do cabealho 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":"<descrio do erro>"}


Http status: 203, 404, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
4.3.5. GetStatus
4.3.5.1.

Introduo

Mtodo para obter o STATUS da respectiva chave de CT-e.


4.3.5.2.

URL:

host>:<port>/<webservice>/api/cte/<chave cte>/getStatus
Verso: 1.22
Atualizado em: 09/06/2015

70

MASTERSAF DFE
4.3.5.3.

INTEGRAO COM WEBSERVICE DF-E V3

Exemplo URL:

http://localhost:8080/webservice/api/cte/<chave cte>/ getStatus


(instalao in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/cte/<chave cte>/ getStatus
(ambiente de homologao do SaaS)
4.3.5.4.

Permisses

Permisses conforme cadastro de usurios:


- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
4.3.5.5.

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
4.3.5.6.

Envio

Nenhum dado alm do cabealho dever ser informado.


4.3.5.7.

Retorno Sucesso

Http status: 200


4.3.5.8.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 203, 404, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
Verso: 1.22
Atualizado em: 09/06/2015

71

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

4.3.6. Consulta Retorno


4.3.6.1.

Introduo

Mtodo para obter os retornos dos documentos enviados, lista de documentos no 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 no informada quantidade no parmetro, ser considerada a quantidade de 50 (cinquenta)
results para cada consulta.
4.3.6.4.

Filtro de Srie

Para filtrar a consulta pela srie, a mesma dever ser enviada na URL. Se houver mais de uma, separlas por vrgula.
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 (instalao in house)


Ou
Verso: 1.22
Atualizado em: 09/06/2015

72

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

https://ws.h.dfe.mastersaf.com.br/api/cte/getRetorno (ambiente de homologao do SaaS)


4.3.6.7.

Permisses

Permisses conforme cadastro de usurios:


- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
4.3.6.8.

Cabealho

Detalhes que devem ser informados na requisio:


-

usar basic authentication utilizando o usurio e

a senha fornecidos.
4.3.6.9.

Envio

Nenhum dado alm do cabealho 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

DESCRIO

retorno

Grupo de informaes para gerao dos arquivos de retorno.

ids
ctes

consultados.
CT-es que foram processadas pelo
software.

loteInutilizado
Consultar arquivo de exemplo: cte_response_getRetorno.txt

Verso: 1.22
Atualizado em: 09/06/2015

73

MASTERSAF DFE
4.3.6.11.

INTEGRAO COM WEBSERVICE DF-E V3

Retorno Erro

No h
4.3.7. Consulta Impresso
4.3.7.1.

Introduo

Mtodo 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 (instalao in house)


Ou
https://ws.h.dfe.mastersaf.com.br/api/cte/getImpressao (ambiente de homologao do SaaS)
4.3.7.4.

Permisses

Permisses conforme cadastro de usurios:


- CT-e Integrador (ROLE_CTE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
4.3.7.5.

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
4.3.7.6.

Envio

Verso: 1.22
Atualizado em: 09/06/2015

74

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Nenhum dado alm do cabealho dever ser informado.


4.3.7.7.

Retorno Sucesso

Response Body: {"impressao":[], "impressaoCCe":[]}


Http status: 200
4.3.7.7.1.

Layout Retorno

CAMPO

DESCRIO

impressao

Lista documentos para impresso.

impressoCCe

Lista de eventos de carta de correo para impresso.

id
nota
Consultar arquivo de exemplo: cte_response_getImpressao.txt
4.3.7.8.

Retorno Erro

No h

5. MDULO MDFE
5.1. OBSERVAES GERAIS
Resumindo o processo, primeiramente enviado um pacote de dados; depois feita uma consulta
recebendo uma lista de ids e, ento por fim, marcam-se no sistema os ids consultados para que numa
prxima consulta eles no sejam retornados novamente, tambm so retornados os MDF-es para
impresso via printer.
Para todos os requests preciso usar basic authentication utilizando o usurio 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 contedo o pipe ( | ). Para quebra de linha usa-se \n.

Verso: 1.22
Atualizado em: 09/06/2015

75

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Para enviar vrios MDF-es voc deve concatenar as strings antes de colocar em txt_contedo.Txt
contedo ter vrios "{"config": " .. ", "xml" : "..."} separando-os por vrgula. No caso de cancelamento e
encerramento o procedimento o mesmo.
5.2. MTODO: POST
5.2.1. EnviarPacote:
5.2.1.1.

Introduo

Mtodo 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 (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/mdfe (ambiente de homologao do SaaS)
5.2.1.4.

Layout

CAMPO

DESCRIO

action

Ao solicitada

Sim

referencia

Nome do arquivo utilizado na integrao.

No

txt_conteudo

Grupo de informaes do MDF-e

Sim

xml
config

CONTEDO

Contedo do XML de MDF-e. Informar dados


conforme layout padro da Receita Federal.
Configuraes.

Permisses

Permisses conforme cadastro de usurios:

Verso: 1.22
Atualizado em: 09/06/2015

Sim
Sim

*Outras tags informadas no sero utilizadas, portanto, no as informe.


5.2.1.5.

OBRIG.

76

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)


- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
5.2.1.6.

Cabealho

Detalhes que devem ser informados na requisio:


-

o usurio 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 mtodo.
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":"<descrio do erro>"}


Http status: 400, 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
5.2.2. Cancelar
5.2.2.1.

Introduo

Mtodo para cancelar MDF-es enviados ao webservice.


5.2.2.2.

URL:

Verso: 1.22
Atualizado em: 09/06/2015

77

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

<host>:<port>/<webservice>/api/mdfe
5.2.2.3.

Exemplo URL:

http://localhost:8080/webservice/api/mdfe (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/mdfe (ambiente de homologao do SaaS)
5.2.2.4.

Layout

CAMPO

DESCRIO

CONTEDO

OBRIG

action

Ao solicitada

Sim

referencia

Nome do arquivo de integrao

No

txt_conteudo

Grupo de informaes de cancelamento.

Sim

Contedo do Cancelamento de MDF-e. Informar dados


xml

conforme layout padro da Receita Federal mais a tag <IE>

Sim

para ser utilizada em processos internos.


config

Configuraes.

Sim

*Outras tags informadas no sero utilizadas, portanto, no as informe.


5.2.2.5.

Permisses

Permisses conforme cadastro de usurios:


- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
5.2.2.6.

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
-

Verso: 1.22
Atualizado em: 09/06/2015

78

MASTERSAF DFE
5.2.2.7.

INTEGRAO COM WEBSERVICE DF-E V3

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 (Solicitao enviada com sucesso)
5.2.2.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 400, 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
5.2.3. Encerrar
5.2.3.1.

Introduo

Mtodo 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 (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/mdfe (ambiente de homologao do SaaS)
5.2.3.4.

Layout

CAMPO

DESCRIO

action

Ao solicitada

Verso: 1.22
Atualizado em: 09/06/2015

CONTEDO
Encerrar

79

OBRIG.
Sim

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

referencia

Nome do arquivo de integrao

No

txt_conteudo

Grupo de informaes de inutilizao.

Sim

Contedo da Inutilizao de MDF-e. Informar dados


xml

conforme layout padro da Receita Federal mais a tag <IE>

Sim

para ser utilizada em processos internos.


config

Configuraes.

Sim

*Outras tags informadas no sero utilizadas, portanto, no as informe.


5.2.3.5.

Permisses

Permisses conforme cadastro de usurios:


- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
5.2.3.6.

Cabealho

Detalhes que devem ser informados na requisio:


-

authentication utilizando o usurio 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 (Solicitao enviada com sucesso)
5.2.3.9.

Retorno Erro

Verso: 1.22
Atualizado em: 09/06/2015

80

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Response Body: {"result":"<descrio do erro>"}


Http status: 400, 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
5.2.4. MarcarConsultado
5.2.4.1.

Introduo

Mtodo para indicar ao WebService que determinados documentos j foram consultados e no precisam
mais ser retornados na consulta (GET).
Deve ser utilizado depois do mtodo de consulta onde so listados os documentos para gerao de
retorno.
5.2.4.2.

URL:

<host>:<port>/<webservice>/api/mdfe
5.2.4.3.

Exemplo URL:

http://localhost:8080/webservice/api/mdfe (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/mdfe (ambiente de homologao do SaaS)
5.2.4.4.

Layout

CAMPO

DESCRIO

action

Ao solicitada

ids

CONTEDO

Sim

Listagem de ids dos processamentos a


serem marcados como consultados.

*Outras tags informadas no sero utilizadas, portanto, no as informe.


5.2.4.5.

Permisses

Permisses conforme cadastro de usurios:


- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
Verso: 1.22
Atualizado em: 09/06/2015

OBRIG.

81

Sim

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

* O usurio informado na requisio deve possuir ao menos uma destas permisses.


5.2.4.6.

Cabealho

Detalhes que devem ser informados na requisio:


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 (Solicitao enviada com sucesso)
5.2.4.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
5.2.5. MarcarImpresso
5.2.5.1.

Introduo

Mtodo para indicar ao WebService que determinados documentos j foram impressos e no precisam
mais ser retornados na consulta (GET).
Deve ser utilizado depois do mtodo de consulta onde so listados os documentos para gerao de
retorno.

Verso: 1.22
Atualizado em: 09/06/2015

82

MASTERSAF DFE
5.2.5.2.

INTEGRAO COM WEBSERVICE DF-E V3

URL:

<host>:<port>/<webservice>/api/mdfe
5.2.5.3.

Exemplo URL:

http://localhost:8080/webservice/api/mdfe (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/mdfe (ambiente de homologao do SaaS)
5.2.5.4.

Layout

CAMPO

DESCRIO

CONTEDO

action

Ao solicitada

Sim

ids

Grupo de informaes para marcar como impresso.

Sim

idProcessamento

Id do processamento a ser marcado.

Sim

idNota

Id da nota a ser marcada.

Sim

*Outras tags informadas no sero utilizadas, portanto, no as informe.


5.2.5.5.

Permisses

Permisses conforme cadastro de usurios:


- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
5.2.5.6.

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
-

5.2.5.7.

Envio

Verso: 1.22
Atualizado em: 09/06/2015

83

OBRIG

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

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 (Solicitao enviada com sucesso)
5.2.5.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
5.3. MTODO: GET
5.3.1. Consulta Padro
5.3.1.1.

Introduo

Mtodo para obter os retornos dos documentos enviados, lista de documentos no 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 (instalao in house)


Ou
https://ws.h.dfe.mastersaf.com.br/api/mdfe (ambiente de homologao do SaaS)
5.3.1.4.

Permisses

Permisses conforme cadastro de usurios:


Verso: 1.22
Atualizado em: 09/06/2015

84

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)


- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
5.3.1.5.

Cabealho

Detalhes que devem ser informados na requisio:


-

preciso usar basic authentication utilizando o usurio e

a senha fornecidos.
5.3.1.6.

Envio

Nenhum dado alm do cabealho 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

DESCRIO

impressao

Lista documentos para impresso.

id
nota
retorno
ids
mdfeCtes

Grupo de informaes para gerao dos arquivos de retorno.


consultados.
MDF-es que foram processadas pelo
software.

Consultar arquivo de exemplo: mdfe_response_get.txt


5.3.1.8.

Retorno Erro

Verso: 1.22
Atualizado em: 09/06/2015

85

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

No h
5.3.2. GetXml
5.3.2.1.

Introduo

Mtodo 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
(instalao in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/mdfe/<chave cte>/getXml
(ambiente de homologao do SaaS)
5.3.2.4.

Permisses

Permisses conforme cadastro de usurios:


- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
5.3.2.5.

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
-

-8859-

correta.
Verso: 1.22
Atualizado em: 09/06/2015

86

Para o xml retornar com a codificao

MASTERSAF DFE
5.3.2.6.

INTEGRAO COM WEBSERVICE DF-E V3

Envio

Nenhum dado alm do cabealho 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":"<descrio do erro>"}


Http status: 203, 404, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
5.3.3. Consulta Retorno
5.3.3.1.

Introduo

Mtodo para obter os retornos dos documentos enviados, lista de documentos no 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 no informada quantidade no parmetro, ser considerada a quantidade de 50 (cinquenta)
results para cada consulta.
5.3.3.4.

Filtro de Srie

Verso: 1.22
Atualizado em: 09/06/2015

87

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Para filtrar a consulta pela srie, a mesma dever ser enviada na URL. Se houver mais de uma, separlas por vrgula.
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 (instalao in house)


Ou
https://ws.h.dfe.mastersaf.com.br/api/mdfe/getRetorno (ambiente de homologao do SaaS)
5.3.3.7.

Permisses

Permisses conforme cadastro de usurios:


- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
5.3.3.8.

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
5.3.3.9.

Envio

Nenhum dado alm do cabealho dever ser informado.


Verso: 1.22
Atualizado em: 09/06/2015

88

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

5.3.3.10. Retorno Sucesso


Response Body: {"retorno":{"mdfeCtes":[],"ids":[]}}
Http status: 200
5.3.3.10.1. Layout Retorno
CAMPO

DESCRIO

retorno

Grupo de informaes para gerao dos arquivos de retorno.

ids

consultados.
-es que foram processadas pelo

mdfeCtes

software.

Consultar arquivo de exemplo: mdfe_response_getRetorno.txt


5.3.3.11.

Retorno Erro

No h
5.3.4. Consulta Impresso
5.3.4.1.

Introduo

Mtodo 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 (instalao in house)


Ou
https://ws.h.dfe.mastersaf.com.br/api/mdfe/getImpressao (ambiente de homologao do SaaS)

Verso: 1.22
Atualizado em: 09/06/2015

89

MASTERSAF DFE
5.3.4.4.

INTEGRAO COM WEBSERVICE DF-E V3

Permisses

Permisses conforme cadastro de usurios:


- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
5.3.4.5.

Cabealho

Detalhes que devem ser informados na requisio:


-

preciso usar basic authentication utilizando o usurio e

a senha fornecidos.
5.3.4.6.

Envio

Nenhum dado alm do cabealho dever ser informado.


5.3.4.7.

Retorno Sucesso

Response Body: {"impressao":[]}


Http status: 200
5.3.4.7.1.

Layout Retorno

CAMPO

DESCRIO

impressao

Lista documentos para impresso.

id
nota
Consultar arquivo de exemplo: mdfe_response_getImpressao.txt
5.3.4.8.

Retorno Erro

No h

Verso: 1.22
Atualizado em: 09/06/2015

90

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

5.3.5. GetDamdfe
5.3.5.1.

Introduo

Mtodo 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
(instalao in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/mdfe/<chave mdfe>/getDamdfe
(ambiente de homologao do SaaS)
5.3.5.4.

Permisses

Permisses conforme cadastro de usurios:


- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
5.3.5.5.

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
5.3.5.6.

Envio

Nenhum dado alm do cabealho dever ser informado.


Verso: 1.22
Atualizado em: 09/06/2015

91

MASTERSAF DFE
5.3.5.7.

INTEGRAO COM WEBSERVICE DF-E V3

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":"<descrio do erro>"}


Http status: 203, 404, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.

6. MDULO RECEPTOR NFSE (SERVIO)


6.1. OBSERVAES GERAIS
Existem poucos mtodos para esse mdulo, existe somente um mtodo POST (MarcarConsultado) e um
mtodo GET (Consulta Padro).
Resumindo o processo, feita uma consulta recebendo uma lista de ids e, ento por fim, marcam-se no
sistema os ids consultados para que, numa prxima consulta, eles no sejam retornados novamente.
6.2. Mtodo: POST
6.2.1. MarcarConsultado:
6.2.1.1.

Introduo

Mtodo para indicar ao WebService que determinados documentos j foram consultados e no precisam
mais ser retornados na consulta (GET).
Deve ser utilizado depois do mtodo de consulta onde so listados os documentos para gerao de
retorno.
6.2.1.2.

URL:

<host>:<port>/<webservice>/api/receptor_nfs
Verso: 1.22
Atualizado em: 09/06/2015

92

MASTERSAF DFE
6.2.1.3.

INTEGRAO COM WEBSERVICE DF-E V3

Exemplo URL:

http://localhost:8080/webservice/api/receptor_nfs (instalao in house)


Ou
https://ws.h.dfe.mastersaf.com.br/api/receptor_nfs (ambiente de homologao do SaaS)
6.2.1.4.

Layout

CAMPO

DESCRIO

action

Ao solicitada

CONTEDO

Sim

Listagem de ids dos processamentos a serem marcados

ids

OBRIG.

como consultados.

Sim

*Outras tags informadas no sero utilizadas, portanto, no as informe.


6.2.1.5.

Permisses

Permisses conforme cadastro de usurios:


- Administrar o sistema (ROLE_SUPER_ADMIN)
6.2.1.6.

Cabealho

Detalhes que devem ser informados na requisio:


-

usar basic authentication utilizando o usurio 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

Verso: 1.22
Atualizado em: 09/06/2015

93

MASTERSAF DFE
6.2.1.8.

INTEGRAO COM WEBSERVICE DF-E V3

Retorno Sucesso

Response Body: {"result":"OK"}


Http status: 200 (Solicitao enviada com sucesso)
6.2.1.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
6.3. MTODO: GET
6.3.1. Consulta Padro
6.3.1.1.

Introduo

Mtodo para obter os retornos dos documentos recebidos e uma lista de documentos no 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 (instalao in house)


Ou
https://ws.h.dfe.mastersaf.com.br/api/receptor_nfs (ambiente de homologao do SaaS)
6.3.1.4.

Permisses

Permisses conforme cadastro de usurios:


- Administrar o sistema (ROLE_SUPER_ADMIN)
6.3.1.5.

Cabealho

Verso: 1.22
Atualizado em: 09/06/2015

94

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Detalhes que devem ser informados na requisio:


-

usar basic authentication utilizando o usurio e

a senha fornecidos.
6.3.1.6.

Envio

Nenhum dado alm do cabealho 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

DESCRIO

retorno

Grupo de informaes para gerao dos arquivos de retorno.

ids
nfss

6.3.1.8.

consultados.
-es que foram processadas pelo
software.
Retorno Erro

No h

7. MDULO RECEPTOR NFE (MERCANTIL)


7.1. OBSERVAES GERAIS
Esse mdulo necessita que sejam enviados os XMLs recebidos de fornecedores e depois que sejam
marcados como consultados.
Como em todos os mdulos existe uma consulta padro (GET) e tambm alguns mtodos para consulta
de XMLs (processados e cancelados).
Verso: 1.22
Atualizado em: 09/06/2015

95

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

7.2. MTODO: POST


7.2.1. EnviarRecebimento
7.2.1.1.

Introduo

Mtodo 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 (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe (ambiente de homologao do SaaS)
7.2.1.4.

Layout

CAMPO

DESCRIO

action

Ao solicitada

Sim

referencia

Nome do arquivo utilizado na integrao.

No

txt_conteudo

CONTEDO

Contedo do XML de NF-e. Informar dados


conforme layout padro da Receita Federal.

*Outras tags informadas no sero utilizadas, portanto, no as informe.


7.2.1.5.

Permisses

Permisses conforme cadastro de usurios:


- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.

Verso: 1.22
Atualizado em: 09/06/2015

96

OBRIG.

Sim

MASTERSAF DFE
7.2.1.6.

INTEGRAO COM WEBSERVICE DF-E V3

Cabealho

Detalhes que devem ser informados na requisio:


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 mtodo.
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

DESCRIO

result
anoMes

Ano e ms da emisso.

cnpjEmitente

CNPJ do Emitente.

recebimento

Tipo

cnpjDestinatario

CNPJ do Destinatrio.

Consultar arquivo de exemplo: receptor_nfe_response_post_enviar_recebimento.txt


7.2.1.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 400, 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.

Verso: 1.22
Atualizado em: 09/06/2015

97

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

7.2.2. EnviarEventoManifestacao
7.2.2.1.

Introduo

Mtodo para envio de eventos de manifestao do destinatrio.


7.2.2.2.

URL:

<host>:<port>/<webservice>/api/recebimentoNfe
7.2.2.3.

Exemplo URL:

http://localhost:8080/webservice/api/recebimentoNfe (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe (ambiente de homologao do SaaS)
7.2.2.4.

Layout

CAMPO

DESCRIO

action

Ao solicitada

referencia

Nome do arquivo utilizado na integrao.

txt_conteudo

CONTEDO
EnviarEventoManifestacao

Contedo do XML de NF-e. Informar dados


conforme layout padro da Receita Federal.

*Outras tags informadas no sero utilizadas, portanto, no as informe.


7.2.2.5.

Permisses

Permisses conforme cadastro de usurios:


- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
7.2.2.6.

Cabealho

Detalhes que devem ser informados na requisio:

Verso: 1.22
Atualizado em: 09/06/2015

98

OBRIG
Sim
No
Sim

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

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 mtodo.
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

DESCRIO

result
descricao

Descrio 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": "No foi encontrada nota recebida com chave de acesso:
12345 para a empresa com CNPJ: 000 e Inscrio 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 ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.

Verso: 1.22
Atualizado em: 09/06/2015

99

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

7.2.3. MarcarConsultado:
7.2.3.1.

Introduo

Mtodo para indicar ao WebService que determinados documentos j foram consultados e no precisam
mais ser retornados na consulta (GET).
Deve ser utilizado depois do mtodo de consulta onde so listados os documentos para gerao de
retorno.
7.2.3.2.

URL:

<host>:<port>/<webservice>/api/recebimentoNfe
7.2.3.3.

Exemplo URL:

http://localhost:8080/webservice/api/recebimentoNfe (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe (ambiente de homologao do SaaS)
7.2.3.4.

Layout

CAMPO

DESCRIO

action

Ao solicitada

CONTEDO

Sim

Listagem de ids dos processamentos a serem

ids

marcados como consultados.

*Outras tags informadas no sero utilizadas, portanto, no as informe.


7.2.3.5.

Permisses

Permisses conforme cadastro de usurios:


- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
7.2.3.6.

Cabealho

Detalhes que devem ser informados na requisio:


Verso: 1.22
Atualizado em: 09/06/2015

OBRIG.

100

Sim

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

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 (Solicitao enviada com sucesso)
7.2.3.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
7.2.4. MarcarImpresso:
7.2.4.1.

Introduo

Mtodo para indicar ao WebService que determinados documentos j foram impressos e no precisam
mais ser retornados na consulta (GET).
Deve ser utilizado depois do mtodo de consulta onde so listados os documentos para gerao de
retorno.
7.2.4.2.

URL:

<host>:<port>/<webservice>/api/recebimentoNfe
Verso: 1.22
Atualizado em: 09/06/2015

101

MASTERSAF DFE
7.2.4.3.

INTEGRAO COM WEBSERVICE DF-E V3

Exemplo URL:

http://localhost:8080/webservice/api/recebimentoNfe (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe (ambiente de homologao do SaaS)
7.2.4.4.

Layout

CAMPO

DESCRIO

CONTEDO

OBRIG

action

Ao solicitada

Sim

ids

Grupo de informaes para marcar como impresso.

Sim

idProcessamento

Id do processamento a ser marcado.

Sim

idNota

Id da nota a ser marcada.

Sim

*Outras tags informadas no sero utilizadas, portanto, no as informe.


7.2.4.5.

Permisses

Permisses conforme cadastro de usurios:


- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
7.2.4.6.

Cabealho

Detalhes que devem ser informados na requisio:


-

authentication utilizando o usurio 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
Verso: 1.22
Atualizado em: 09/06/2015

102

MASTERSAF DFE
7.2.4.8.

INTEGRAO COM WEBSERVICE DF-E V3

Retorno Sucesso

Response Body: {"result":"OK"}


Http status: 200 (Solicitao enviada com sucesso)
7.2.4.9.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
7.3. MTODO: GET
7.3.1. Consulta Padro
7.3.1.1.

Introduo

Mtodo para obter os retornos dos documentos enviados e a lista de documentos no consultados.
7.3.1.2.

URL:

<host>:<port>/<webservice>/api/recebimentoNfe
7.3.1.3.

Exemplo URL:

http://localhost:8080/webservice/api/recebimentoNfe (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe (ambiente de homologao do SaaS)
7.3.1.4.

Permisses

Permisses conforme cadastro de usurios:


- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
Verso: 1.22
Atualizado em: 09/06/2015

103

MASTERSAF DFE
7.3.1.5.

INTEGRAO COM WEBSERVICE DF-E V3

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
7.3.1.6.

Envio

Nenhum dado alm do cabealho 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

DESCRIO

Retorno

Grupo de informaes para gerao 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

No h
7.3.2. GetXml
7.3.2.1.

Introduo

Mtodo para obter o XML processado da respectiva chave de NF-e.


Verso: 1.22
Atualizado em: 09/06/2015

104

MASTERSAF DFE
7.3.2.2.

INTEGRAO COM WEBSERVICE DF-E V3

URL:

<host>:<port>/<webservice>/api/recebimentoNfe/<chave nfe>/getXml
7.3.2.3.

Exemplo URL:

http://localhost:8080/webservice/api/recebimentoNfe/<chave nfe>/getXml
(instalao in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe/<chave nfe>/getXml
(ambiente de homologao do SaaS)
7.3.2.4.

Permisses

Permisses conforme cadastro de usurios:


- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
7.3.2.5.

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
-

-8859-

correta.
7.3.2.6.

Envio

Nenhum dado alm do cabealho dever ser informado.


7.3.2.7.

Retorno Sucesso

Response Body: XML processado.


Verso: 1.22
Atualizado em: 09/06/2015

105

Para o xml retornar com a codificao

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Http status: 200


Consultar arquivo de exemplo: receptor_nfe_response_get_xml.txt
7.3.2.8.

Retorno Erro

Response Body: {"result":"<descrio do erro>"}


Http status: 203, 404, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
7.3.3. GetXmlCancelamento
7.3.3.1.

Introduo

Mtodo 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
(instalao in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe/<chave nfe>/getXmlCancelamento
(ambiente de homologao do SaaS)
7.3.3.4.

Permisses

Permisses conforme cadastro de usurios:


- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.

Verso: 1.22
Atualizado em: 09/06/2015

106

MASTERSAF DFE
7.3.3.5.

INTEGRAO COM WEBSERVICE DF-E V3

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
-

-8859-

Para o xml retornar com a codificao

correta.
7.3.3.6.

Envio

Nenhum dado alm do cabealho 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":"<descrio do erro>"}


Http status: 203, 404, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
7.3.4. GetStatus
7.3.4.1.

Introduo

Mtodo para obter o Status (Cdigo-Descrio) da respectiva chave de NF-e.


7.3.4.2.

URL:

<host>:<port>/<webservice>/api/ recebimentoNfe/<chave nfe>/getStatus

Verso: 1.22
Atualizado em: 09/06/2015

107

MASTERSAF DFE
7.3.4.3.

INTEGRAO COM WEBSERVICE DF-E V3

Exemplo URL:

http://localhost:8080/webservice/api/recebimentoNfe/<chave nfe>/getStatus
(instalao in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe/<chave nfe>/getStatus
(ambiente de homologao do SaaS)
7.3.4.4.

Permisses

Permisses conforme cadastro de usurios:


- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
7.3.4.5.

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
7.3.4.6.

Envio

Nenhum dado alm do cabealho dever ser informado.


7.3.4.7.

Retorno Sucesso

Response Body: {"retorno":{"recebimentos":[],"ids":[]}}


Http status: 200
7.3.4.8.

Layout Retorno

CAMPO

DESCRIO

Retorno

Grupo de informaes para gerao dos arquivos de retorno.

Ids

No h.

Verso: 1.22
Atualizado em: 09/06/2015

108

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Recebimentos
7.3.4.9.

-es que foram solicitados.

Retorno Erro

No h
7.3.5. Consulta Impresso
7.3.5.1.

Introduo

Mtodo 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 (instalao in house)


Ou
https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe/getImpressao (ambiente de homologao do
SaaS)
7.3.5.4.

Permisses

Permisses conforme cadastro de usurios:


- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
7.3.5.5.

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
Verso: 1.22
Atualizado em: 09/06/2015

109

MASTERSAF DFE
7.3.5.6.

INTEGRAO COM WEBSERVICE DF-E V3

Envio

Nenhum dado alm do cabealho dever ser informado.


7.3.5.7.

Retorno Sucesso

Response Body: {"impressao":[]}


Http status: 200
7.3.5.7.1.

Layout Retorno

CAMPO

DESCRIO

impressao

Lista documentos para impresso.

idProcessamento
params
Consultar arquivo de exemplo: receptor_nfe_response_getImpressao.txt
7.3.5.8.

Retorno Erro

No h

8. MDULO RECEPTOR CTE


8.1. OBSERVAES GERAIS
Esse mdulo necessita que sejam enviados os XMLs recebidos e depois que sejam marcados como
consultados. possvel ainda consultar um documento e obter o seu XML.
Como em todos os mdulos existe uma consulta padro (GET) e tambm alguns mtodos para consulta
de XMLs (processados e cancelados).
8.2. MTODO: POST
8.2.1. EnviarRecebimento

Verso: 1.22
Atualizado em: 09/06/2015

110

MASTERSAF DFE
8.2.1.1.

INTEGRAO COM WEBSERVICE DF-E V3

Introduo

Mtodo 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 (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/recebimento (ambiente de homologao do SaaS)
8.2.1.4.

Layout

CAMPO

DESCRIO

action

Ao solicitada

Sim

referencia

Nome do arquivo utilizado na integrao.

No

txt_conteudo

CONTEDO

Contedo do XML de CT-e. Informar dados


conforme layout padro da Receita Federal.

OBRIG

Sim

*Outras tags informadas no sero utilizadas, portanto, no as informe.


8.2.1.5.

Permisses

Permisses conforme cadastro de usurios:


- 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 usurio informado na requisio deve possuir ao menos uma destas permisses.
8.2.1.6.

Cabealho

Detalhes que devem ser informados na requisio:

Verso: 1.22
Atualizado em: 09/06/2015

111

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

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 mtodo.
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

DESCRIO

result
anoMes

Ano e ms da emisso.

cnpjEmitente

CNPJ do Emitente.

Recebimento
cnpjDestinatario

CNPJ do Destinatrio.

Consultar arquivo de exemplo: receptor_cte_response_post_enviar_recebimento.txt


8.2.1.9.

Retorno Erro

Response Body: { result : <descrio do erro> }


Http status: 400, 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
8.2.2. ConsultarDocFornecedor
8.2.2.1.

Introduo

Verso: 1.22
Atualizado em: 09/06/2015

112

: }

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Mtodo para consultar status de CT-e recebido. A consulta pode ser feita usando a chave do documento
ou atravs da combinao de CNPJ, IE, nmero e srie.
8.2.2.2.

URL:

<host>:<port>/<webservice>/api/recebimento
8.2.2.3.

Exemplo URL:

http://localhost:8080/webservice/api/recebimento (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/recebimento (ambiente de homologao do SaaS)
8.2.2.4.

Layout

CAMPO

DESCRIO

action

Ao solicitada

txt_conteudo

Grupo de informaes para consulta.

tpDoc

CONTEDO
ConsultarDocFornecedor

OBRIG
Sim
Sim

para consulta.

Sim

-e.
chave

Informar quando no for informar os outros

cnpj

No

No
informado.

ie

No
Nmero do CT-e.

nrDoc

No
informado.
-e. No

serie

*Outras tags informadas no sero utilizadas, portanto, no as informe.


8.2.2.5.

Permisses

Verso: 1.22
Atualizado em: 09/06/2015

113

No

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Permisses conforme cadastro de usurios:


- 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 usurio informado na requisio deve possuir ao menos uma destas permisses.
8.2.2.6.

Cabealho

Detalhes que devem ser informados na requisio:


-

preciso usar basic authentication utilizando o usurio 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 mtodo.
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

DESCRIO

result
status

Verso: 1.22
Atualizado em: 09/06/2015

Cdigo do status do documento.

114

MASTERSAF DFE
8.2.2.9.

INTEGRAO COM WEBSERVICE DF-E V3

Retorno Erro

Response Body: { result : <descrio do erro> }


Http status: 400, 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
8.2.3. ResgatarXmlFornecedor
8.2.3.1.

Introduo

Mtodo para resgatar XML de CT-e recebido. A consulta pode ser feita usando a chave do documento ou
atravs da combinao de CNPJ, IE, nmero e srie.
8.2.3.2.

URL:

<host>:<port>/<webservice>/api/recebimento
8.2.3.3.

Exemplo URL:

http://localhost:8080/webservice/api/recebimento (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/recebimento (ambiente de homologao do SaaS)
8.2.3.4.

Layout

CAMPO

DESCRIO

action

Ao solicitada

txt_conteudo

Grupo de informaes para consulta.

tpDoc

CONTEDO
ResgatarXmlFornecedor

OBRIG
Sim
Sim

Atributo

para consulta.

Sim

-e.
chave

Informar quando no for informar os outros

No

cnpj

No

No

informado.
Verso: 1.22
Atualizado em: 09/06/2015

115

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

ie

No
-e. No

nrDoc

-e. No

serie

*Outras tags informadas no sero utilizadas, portanto, no as informe.


8.2.3.5.

Permisses

Permisses conforme cadastro de usurios:


- 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 usurio informado na requisio deve possuir ao menos uma destas permisses.
8.2.3.6.

Cabealho

Detalhes que devem ser informados na requisio:


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 mtodo.
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

Verso: 1.22
Atualizado em: 09/06/2015

116

No
No

MASTERSAF DFE
8.2.3.8.

INTEGRAO COM WEBSERVICE DF-E V3

Retorno Sucesso

Response Body: { result : OK , status :100}


Http status: 202
8.2.3.8.1. Layout Retorno
CAMPO

DESCRIO

result
xml

Contedo do XML.

Consultar arquivo de exemplo: receptor_cte_response_post_resgatar_xml_fornecedor.txt


8.2.3.9.

Retorno Erro

Response Body: { result : <descrio do erro> }


Http status: 400, 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
8.2.4. MarcarConsultado:
8.2.4.1.

Introduo

Mtodo para indicar ao WebService que determinados documentos j foram consultados e no precisam
mais ser retornados na consulta (GET).
Deve ser utilizado depois do mtodo de consulta onde so listados os documentos para gerao de
retorno.
8.2.4.2.

URL:

<host>:<port>/<webservice>/api/recebimento
8.2.4.3.

Exemplo URL:

http://localhost:8080/webservice/api/recebimento (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/recebimento (ambiente de homologao do SaaS)
Verso: 1.22
Atualizado em: 09/06/2015

117

MASTERSAF DFE
8.2.4.4.

INTEGRAO COM WEBSERVICE DF-E V3

Layout

CAMPO

DESCRIO

action

Ao solicitada

CONTEDO

Sim

Listagem de ids dos processamentos a serem marcados

ids

OBRIG

como consultados.

Sim

*Outras tags informadas no sero utilizadas, portanto, no as informe.


8.2.4.5.

Permisses

Permisses conforme cadastro de usurios:


- 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 usurio informado na requisio deve possuir ao menos uma destas permisses.
8.2.4.6.

Cabealho

Detalhes que devem ser informados na requisio:


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

Verso: 1.22
Atualizado em: 09/06/2015

118

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Response Body: { result : OK }


Http status: 200 (Solicitao enviada com sucesso)
8.2.4.9.

Retorno Erro

Response Body: { result : <descrio do erro> }


Http status: 412, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
8.3. MTODO: GET
8.3.1. Consulta Padro
8.3.1.1.

Introduo

Mtodo para obter os retornos dos documentos enviados e a lista de documentos no consultados.
8.3.1.2.

URL:

<host>:<port>/<webservice>/api/recebimento
8.3.1.3.

Exemplo URL:

http://localhost:8080/webservice/api/recebimento (instalao in house)


ou
https://ws.h.dfe.mastersaf.com.br/api/recebimento (ambiente de homologao do SaaS)
8.3.1.4.

Permisses

Permisses conforme cadastro de usurios:


- 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 usurio informado na requisio deve possuir ao menos uma destas permisses.

Verso: 1.22
Atualizado em: 09/06/2015

119

MASTERSAF DFE
8.3.1.5.

INTEGRAO COM WEBSERVICE DF-E V3

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
8.3.1.6.

Envio

Nenhum dado alm do cabealho 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

DESCRIO

Retorno

Grupo de informaes para gerao dos arquivos de retorno.


ds dos processamentos que constam como no

Ids

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

No h
8.3.2. GetXml
8.3.2.1.

Introduo

Mtodo para obter o XML processado da respectiva chave de CT-e.

Verso: 1.22
Atualizado em: 09/06/2015

120

MASTERSAF DFE
8.3.2.2.

INTEGRAO COM WEBSERVICE DF-E V3

URL:

<host>:<port>/<webservice>/api/recebimento/<chave cte>/getXml
8.3.2.3.

Exemplo URL:

http://localhost:8080/webservice/api/recebimento/<chave cte>/getXml
(instalao in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/recebimento/<chave cte>/getXml
(ambiente de homologao do SaaS)
8.3.2.4.

Permisses

Permisses conforme cadastro de usurios:


- 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 usurio informado na requisio deve possuir ao menos uma destas permisses.
8.3.2.5.

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
-

-8859-

correta.
8.3.2.6.

Envio

Nenhum dado alm do cabealho dever ser informado.


8.3.2.7.

Retorno Sucesso

Verso: 1.22
Atualizado em: 09/06/2015

121

Para o xml retornar com a codificao

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

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 : <descrio do erro> }


Http status: 203, 404, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
8.3.3. GetXmlCancelamento
8.3.3.1.

Introduo

Mtodo 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
(instalao in house)
ou
https://ws.h.dfe.mastersaf.com.br/api/recebimento/<chave cte>/getXmlCancelamento
(ambiente de homologao do SaaS)
8.3.3.4.

Permisses

Permisses conforme cadastro de usurios:


- 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 usurio informado na requisio deve possuir ao menos uma destas permisses.
Verso: 1.22
Atualizado em: 09/06/2015

122

MASTERSAF DFE
8.3.3.5.

INTEGRAO COM WEBSERVICE DF-E V3

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
-

-8859-

Para o xml retornar com a codificao

correta.
8.3.3.6.

Envio

Nenhum dado alm do cabealho 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 : <descrio do erro> }


Http status: 203, 404, 500.
*Consultar ttulo LISTAGEM DE ERROS para maiores informaes sobre os erros.
8.3.4. GetStatus
8.3.4.1.

Introduo

Mtodo para obter o Status (Cdigo-Descrio) da respectiva chave de CT-e.


8.3.4.2.

URL:

<host>:<port>/<webservice>/api/recebimento/<chave nfe>/getStatus
Verso: 1.22
Atualizado em: 09/06/2015

123

MASTERSAF DFE
8.3.4.3.

INTEGRAO COM WEBSERVICE DF-E V3

Exemplo URL:

http://localhost:8080/webservice/api/recebimento/<chave nfe>/getStatus
(instalao in house)
Ou
https://ws.h.dfe.mastersaf.com.br/api/recebimento/<chave nfe>/getStatus
(ambiente de homologao do SaaS)
8.3.4.4.

Permisses

Permisses conforme cadastro de usurios:


- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)
- Administrar o sistema (ROLE_SUPER_ADMIN)
* O usurio informado na requisio deve possuir ao menos uma destas permisses.
8.3.4.5.

Cabealho

Detalhes que devem ser informados na requisio:


a senha fornecidos.
8.3.4.6.

Envio

Nenhum dado alm do cabealho dever ser informado.


8.3.4.7.

Retorno Sucesso

Response Body: { retorno :{ recebimentos :[], ids :[]}}


Http status: 200
8.3.4.8.

Layout Retorno

CAMPO

DESCRIO

Retorno

Grupo de informaes para gerao dos arquivos de retorno.

Ids

No h.

Verso: 1.22
Atualizado em: 09/06/2015

124

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Recebimentos
8.3.4.9.

CT-es que foram solicitados.

Retorno Erro

No h

9. LISTAGEM DE ERROS
- 203

Usurio e senha sem permisso de acessar o mtodo/dados da empresa.

- 400

Erros ao de validao/parser/argumentos ilegais descritos no Response Body.

- 403

Forbidden Usurio e senha no foram informados corretamente.

- 404

Chave de acesso no encontrada.

- 412 JSON nao informado ou invalido ou nenhuma ao (campo action) encontrada.


- 415 Unsupported Media Type
- 500

125todos125-type no foi informado corretamente.

Erro interno.

Mais informaes sobre os cdigos 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.

OBSERVAES GERAIS

Utilize a extenso REST Client do Firefox para realizar os testes de comunicao.


http://restclient.net/

Verso: 1.22
Atualizado em: 09/06/2015

125

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

10.2. UTILIZANDO A EXTENSO REST CLIENT DO FIREFOX


10.2.1. Como informar os dados?
1) Informar tipo de requisio

2) Informar a URL:

3) Informando usurio e senha:

Verso: 1.22
Atualizado em: 09/06/2015

126

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

Informar o usurio e senha:

4) Informando dados no cabealho (Content-type se necessrio):


Selecionar menu

Informar dados de tipo de contedo, por exemplo:

Verso: 1.22
Atualizado em: 09/06/2015

127

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

5) Informando contedo (corpo) da mensagem (se necessrio):

10.2.2. Exemplo de POST

Verso: 1.22
Atualizado em: 09/06/2015

128

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

10.2.3. Exemplo de GET

11. PROGRAMA EXEMPLO EM JAVA


Junto deste Manual est disponvel o cdigo fonte de software capaz de testar os servios 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 opo pelo menu File
-> Import -> Existing Maven Projects
2) Com o projeto importado, abrir a classe br.com.mastersaf.WSTest (Para testar mtodo POST
enviarPacote da NF-e) ou br.com.mastersaf.WSPdfDacteTest (Teste para mtodo GET getDacte do CT-e)
2.1) Configurar os atributos URL_WEBSERVICE, USER e PASSWORD
2.2) O usurio informado dever ter a permisso de integrador no portal MASTERSAF.

Verso: 1.22
Atualizado em: 09/06/2015

129

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3

2.3) Retornar no mtodo getBodyRequest, o json da NFE com os seus dados. Este formato foi o mesmo
descrito neste manual.

12.

RELAO DE MUDANAS DE VERSES DO MANUAL

Verso

Data

1.00

22/08/2012

1.01

25/09/2012

Includo captulo 5

MDF-E

1.02

08/10/2012

Includo item 3.3.4

GetDanfe

Includo item 3.3.5

GetStatus

1.03

29/11/2012

Mudanas

Verso DF-e

Criao do manual baseado em MASTERSAFDFE


Integrao com Webservice.pdf

Includo captulo 12 Relao das Mudanas de Verses do

3.13.2

Manual
1.04

27/03/2013

1.05

05/04/2013

1.06

11/04/2013

1.07

13/05/2013
26/06/2013

Includos itens 3.3.6, 3.3.7, 4.3.5, 4.3.6, 5.3.3, 5.3.4


Includo exemplo de retorno do mtodo GET para o mdulo
Receptor NFS-e.
Includo item 7.2.2 referente a Eventos de Manifestao.
Includos itens 3.3.6.3 e 3.3.6.4 referentes a Filtro do
mtodo getRetorno.

08/08/2013

3.16.1
3.16.1
3.17.0

Alterado nomes dos mtodos getXmlCancelado para ficar


igual ao nome no produto (getXmlCancelamento).

1.08

3.16.0

Includo item 4.3.5

3.19.1

GetStatus

Includa informao de charset na parte de cabealhos dos


1.09

16/08/2013

mtodos getXml e getXmlCancelamento para todos os

3.19.1

modulos
1.10

19/08/2013

Atualizado item 3.3.5.7

Retorno Sucesso

Adicionado item 3.3.5.8

Layout Retorno

Adicionado item 2.3.1.3

Definir quantidade de Results da

3.19.2

consulta

1.11

20/09/2013

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


Verso: 1.22
Atualizado em: 09/06/2015

Layout Retorno
130

3.20.1

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3


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
Alterao deste manual para incluir um novo arquivo de
exemplo nfe_request_post_enviar_pacote_3.txt com todos
os 131todos131f131 corretos referentes 131todos131f para
1.13

01/04/2014

filtro de 131todos131f. O mesmo encontra-se no pacote.


Alterao neste manual, no ponto 3.2.1.4 de post Nfe onde
diz: 131todos131f

3.24.2

Informaes para contingncia, pois

seguem mais informaes, alm das informaes de


contingencia dentro do atributo 131todos131f.
1.14

05/05/2014

1.15

22/07/2014

1.16

19/08/2014

Atualizado item 2.3.1.8.1

Layout Retorno

padronizao do retorno.
Includo item: 4.2.3 EnviarCartaCorrecaoCte.
Atualizado 4.3.1

ConsultaPadrao mdulo CT-e.

Includo item 2.2.6

Convertida, do mdulo NFS-e.

3.25.2
3.27.1
3.28.0

Incluido mtodo getStatus para Recebimento NFE/CTE


1.17

02/09/2014

3.28.1
Saas.
Atualizado para alguns mtodos do mdulo nfe o novo

1.18

31/10/2014

1.19

25/11/2014

1.20

29/12/2014

1.20

30/12/2014

3.2.7

MarcarCartaCorrecaoImpresso

Incluindo mtodo

3.13.0

1.20

30/12/2014

4.2.7

MarcarCartaCorrecaoImpresso

Incluindo mtodo

3.27.1

1.20

30/12/2014

4.3.6

Consulta Retorno

Verso: 1.22
Atualizado em: 09/06/2015

parmetro na requisio id_integrador


Atualizado a estrutura de retorno para 131todos GET com
novo parmetro contendo link de acesso direto ao DANFE.
2.3.1 Consulta Padro

Atualizado parmetros de filtro

disponveis.

Atualizado parmetros de filtro

disponveis.
131

3.30.0
3.30.1
3.26.0

3.25.3

MASTERSAF DFE

INTEGRAO COM WEBSERVICE DF-E V3


5.3.3

Consulta Retorno

Atualizado parmetros de filtro

1.20

30/12/2014

1.20

30/12/2014

5.3.5 GetDamdfe

1.20

30/12/2014

7.2.4

1.20

30/12/2014

7.3.5 Consulta Impresso

1.21

12/05/2015

disponveis.
Incluindo mtodo.

MarcarImpresso Incluindo mtodo


Incluindo mtodo

Atualizando arquivos de exemplo de consulta de MDF-e.


Itens do manual: 5.3.1 e 5.3.3

3.25.3
3.27.0
3.19.1
3.19.1
3.34.1

Atualizando arquivos de exemplo de consulta de NF-e. Itens


1.21

12/05/2015

do manual:

3.34.1

3.3.1 - Consulta Padro


3.3.7 - Consulta Retorno
Atualizando arquivos de exemplo de consulta de CT-e. Itens

1.21

12/05/2015

do manual:

3.34.1

4.3.1 - Consulta Padro


4.3.7 - Consulta Retorno

13. SUPORTE TCNICO


Para dvidas ou problemas, abra um chamado no Contact Center ou entre em contato com nossa equipe
de Suporte Tcnico MASTERSAF pelo Telefone:
(11) 2159-0600 opo 02 (Atendimento das Solues DFE).
Nosso horrio de atendimento de segunda sexta-feira de 09h s 18h.

Verso: 1.22
Atualizado em: 09/06/2015

132