132
INTEGRAÇÃO COM WEBSERVICE DFE V3

MASTERSAFDFE_11 - INTEGRAÇÃO COM WEBSERVICE.pdf

Embed Size (px)

Citation preview

INTEGRAÇÃO COM WEBSERVICE DFE V3

2

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

ÍNDICE

1. INTRODUÇÃO .............................................................................................................................................. 6

2. MÓDULO NFSE (SERVIÇO) ......................................................................................................................... 6

2.1. OBSERVAÇÕES GERAIS ........................................................................................................................... 6 2.2. MÉTODO: POST ........................................................................................................................................ 6 2.2.1. ENVIARPACOTE ..................................................................................................................................................... 6

2.2.2. CANCELAR ............................................................................................................................................................ 8

2.2.3. MARCARCONSULTADO: ....................................................................................................................................... 10

2.2.4. CONSULTARRPSSAGUARDANDODOWNLOAD: ....................................................................................................... 11

2.2.5. UPLOADRETORNOPREFEITURA: ........................................................................................................................... 13

2.2.6. CONVERTIDA: ...................................................................................................................................................... 15

2.3. MÉTODO: GET ........................................................................................................................................ 17 2.3.1. CONSULTA PADRÃO ............................................................................................................................................ 17

3. MÓDULO NFE (MERCANTIL) .................................................................................................................... 19

3.1. OBSERVAÇÕES GERAIS .......................................................................................................................... 19 3.2. MÉTODO: POST ...................................................................................................................................... 19 3.2.1. ENVIARPACOTE: .................................................................................................................................................. 19

3.2.2. CANCELAR .......................................................................................................................................................... 21

3.2.3. INUTILIZAR .......................................................................................................................................................... 23

3.2.4. ENVIARCARTACORRECAONFE .............................................................................................................................. 24

3.2.5. MARCARCONSULTADO ........................................................................................................................................ 26

3.2.6. MARCARIMPRESSO .............................................................................................................................................. 28

3.2.7. MARCARCARTACORRECAOIMPRESSO ................................................................................................................... 29

3.2.8. REIMPRESSAODANFE .......................................................................................................................................... 31

3.2.9. CONSULTAR CADASTRO ....................................................................................................................................... 33

3.3. MÉTODO: GET ........................................................................................................................................ 35 3.3.1. CONSULTA PADRÃO:............................................................................................................................................ 35

3.3.2. GETXML .............................................................................................................................................................. 38

3.3.3. GETXMLCANCELAMENTO ..................................................................................................................................... 39

3.3.4. GETDANFE .......................................................................................................................................................... 40

3.3.5. GETSTATUS ......................................................................................................................................................... 42

3.3.6. GETSTATUS (COM PARÂMETROS) .......................................................................................................................... 43

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

3

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

3.3.8. CONSULTA IMPRESSÃO: ....................................................................................................................................... 47

3.3.9. CONSULTA IMPRESSÃO NFE: ................................................................................................................................ 49

3.3.10. CONSULTA IMPRESSÃO CARTA CORREÇÃO NFE: ................................................................................................... 50

4. MÓDULO CTE ............................................................................................................................................ 52

4.1. OBSERVAÇÕES GERAIS ......................................................................................................................... 52 4.2. MÉTODO: POST ...................................................................................................................................... 52 4.2.1. ENVIARPACOTE: .................................................................................................................................................. 53

4.2.2. CANCELAR .......................................................................................................................................................... 54

4.2.3. ENVIARCARTACORRECAOCTE .............................................................................................................................. 56

4.2.4. INUTILIZAR .......................................................................................................................................................... 57

4.2.5. MARCARCONSULTADO ........................................................................................................................................ 59

4.2.6. MARCARIMPRESSO .............................................................................................................................................. 61

4.2.7. MARCARCARTACORRECAOIMPRESSO ................................................................................................................... 62

4.3. MÉTODO: GET ........................................................................................................................................ 64 4.3.1. CONSULTA PADRÃO ............................................................................................................................................ 64

4.3.2. GETXML .............................................................................................................................................................. 66

4.3.3. GETXMLCANCELAMENTO ..................................................................................................................................... 68

4.3.4. GETDACTE .......................................................................................................................................................... 69

4.3.5. GETSTATUS ......................................................................................................................................................... 70

4.3.6. CONSULTA RETORNO .......................................................................................................................................... 72

4.3.7. CONSULTA IMPRESSÃO ........................................................................................................................................ 74

5. MÓDULO MDFE ......................................................................................................................................... 75

5.1. OBSERVAÇÕES GERAIS ......................................................................................................................... 75 5.2. MÉTODO: POST ...................................................................................................................................... 76 5.2.1. ENVIARPACOTE: .................................................................................................................................................. 76

5.2.2. CANCELAR .......................................................................................................................................................... 77

5.2.3. ENCERRAR .......................................................................................................................................................... 79

5.2.4. MARCARCONSULTADO ........................................................................................................................................ 81

5.2.5. MARCARIMPRESSO .............................................................................................................................................. 82

5.3. MÉTODO: GET ........................................................................................................................................ 84 5.3.1. CONSULTA PADRÃO ............................................................................................................................................ 84

5.3.2. GETXML .............................................................................................................................................................. 86

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

5.3.4. CONSULTA IMPRESSÃO ........................................................................................................................................ 89

5.3.5. GETDAMDFE ....................................................................................................................................................... 91

4

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

6. MÓDULO RECEPTOR NFSE (SERVIÇO) .................................................................................................... 92

6.1. OBSERVAÇÕES GERAIS ......................................................................................................................... 92 6.2. MÉTODO: POST ........................................................................................................................................ 92 6.2.1. MARCARCONSULTADO: ....................................................................................................................................... 92

6.3. MÉTODO: GET ........................................................................................................................................ 94 6.3.1. CONSULTA PADRÃO ............................................................................................................................................ 94

7. MÓDULO RECEPTOR NFE (MERCANTIL) ................................................................................................. 95

7.1. OBSERVAÇÕES GERAIS .......................................................................................................................... 95 7.2. MÉTODO: POST ...................................................................................................................................... 96 7.2.1. ENVIARRECEBIMENTO .......................................................................................................................................... 96

7.2.2. ENVIAREVENTOMANIFESTACAO ........................................................................................................................... 98

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

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

7.3. MÉTODO: GET....................................................................................................................................... 103 7.3.1. CONSULTA PADRÃO .......................................................................................................................................... 103

7.3.2. GETXML ............................................................................................................................................................ 104

7.3.3. GETXMLCANCELAMENTO ................................................................................................................................... 106

7.3.4. GETSTATUS ....................................................................................................................................................... 107

7.3.5. CONSULTA IMPRESSÃO ...................................................................................................................................... 109

8. MÓDULO RECEPTOR CTE ....................................................................................................................... 110

8.1. OBSERVAÇÕES GERAIS ....................................................................................................................... 110 8.2. MÉTODO: POST .................................................................................................................................... 110 8.2.1. ENVIARRECEBIMENTO ........................................................................................................................................ 110

8.2.2. CONSULTARDOCFORNECEDOR .......................................................................................................................... 112

8.2.3. RESGATARXMLFORNECEDOR ............................................................................................................................. 115

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

8.3. MÉTODO: GET ...................................................................................................................................... 119 8.3.1. CONSULTA PADRÃO .......................................................................................................................................... 119

8.3.2. GETXML ............................................................................................................................................................ 120

8.3.3. GETXMLCANCELAMENTO ................................................................................................................................... 122

8.3.4. GETSTATUS ....................................................................................................................................................... 123

9. LISTAGEM DE ERROS ............................................................................................................................. 125

10. EXEMPLO DE COMO UTILIZAR O WEBSERVICE .................................................................................. 125

10.1. OBSERVAÇÕES GERAIS ...................................................................................................................... 125 10.2. UTILIZANDO A EXTENSÃO REST CLIENT DO FIREFOX ..................................................................... 126

5

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

10.2.1. COMO INFORMAR OS DADOS? ............................................................................................................................. 126

10.2.2. EXEMPLO DE POST ........................................................................................................................................... 128

10.2.3. EXEMPLO DE GET .............................................................................................................................................. 129

11. PROGRAMA EXEMPLO EM JAVA ........................................................................................................... 129

12. RELAÇÃO DE MUDANÇAS DE VERSÕES DO MANUAL ........................................................................ 130

13. SUPORTE TÉCNICO ............................................................................................................................... 132

6

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

1. INTRODUÇÃO

O módulo Webservice da Solução MASTERSAF DFE V3 é baseado em requisições REST. Utilizamos dois

tipos de requisições: POST e GET. Todas as requisições exigem um usuário e senha informados por Basic

Authentication.

As requisições do tipo POST exigem algum conteúdo (Request Body). É através desse conteúdo que a

requisição será processada.

Nas requisições do tipo GET não é necessário informar nenhum conteúdo, pois na própria URL serão

passados os parâmetros.

2. MÓDULO NFSE (SERVIÇO)

2.1. OBSERVAÇÕES GERAIS

Resumindo o processo, primeiramente é enviado um pacote de dados; depois é feita uma consulta

recebendo uma lista de ids e, então por fim, marcam-se no sistema os ids consultados para que numa

próxima consulta eles não sejam retornados novamente.

Com isso basta realizar POST para enviar os pacotes e GET para consultar o resultado do

processamento.

2.2. MÉTODO: POST

2.2.1. EnviarPacote

2.2.1.1. Introdução

Método utilizado para enviar RPSs ao WebService.

2.2.1.2. URL:

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

7

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

2.2.1.3. Exemplo URL:

http://localhost:8080/webservice/api/dfe (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/dfe (ambiente de homologação do SaaS)

2.2.1.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG

action Ação solicitada EnviarPacote Sim

txt_conteudo Conteúdo do RPS. Informar dados do RPS

conforme layout padrão do produto. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

2.2.1.5. Permissões

Permissões conforme cadastro de usuários:

- NFS-e Integrador (ROLE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

2.2.1.6. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- -

2.2.1.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "txt_conteudo".

O separador de campos do conteúdo é o pipe ( | ). Para quebra de linha usa-se \n.

8

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Para enviar vários RPSs você deve concatenar as strings antes de colocar em txt_conteúdo (txt conteúdo

terá vários "__rps__|versao=1(...)"), mas só pode existir um "__arquivo_fim__|". No caso de cancelamento o

procedimento é o mesmo (vários __cancelamento__ e apenas um __arquivo_fim__|).

Exemplo de Request Body conforme arquivo de exemplo: nfse_request_post_enviar_pacote.txt

2.2.1.8. Retorno Sucesso

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

Http status: 202

2.2.1.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 400, 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

2.2.2. Cancelar

2.2.2.1. Introdução

Método para cancelar RPSs enviados ao webservice.

2.2.2.2. URL:

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

2.2.2.3. Exemplo URL:

http://localhost:8080/webservice/api/dfe (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/dfe (ambiente de homologação do SaaS)

2.2.2.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG.

action Ação solicitada Cancelar Sim

9

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

txt_conteudo Conteúdo do Cancelamento de RPS. Informar dados do

RPS conforme layout padrão do produto. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

2.2.2.5. Permissões

Permissões conforme cadastro de usuários:

- NFS-e Integrador (ROLE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

2.2.2.6. Cabeçalho

Detalhes que devem ser informados na requisição:

- authentication utilizando o usuário e

a senha fornecidos.

- -

2.2.2.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "txt_conteudo".

O separador de campos do conteúdo é o pipe ( | ).

Exemplo de Request Body conforme arquivo de exemplo: nfse_request_post_cancelar.txt

2.2.2.8. Retorno Sucesso

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

Http status: 200 (Solicitação enviada com sucesso)

2.2.2.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

10

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Http status: 400, 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

2.2.3. MarcarConsultado:

2.2.3.1. Introdução

Método para indicar ao WebService que determinados documentos já foram consultados e não precisam

mais ser retornados na consulta (GET).

Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de

retorno.

2.2.3.2. URL:

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

2.2.3.3. Exemplo URL:

http://localhost:8080/webservice/api/dfe (instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/dfe (ambiente de homologação do SaaS)

2.2.3.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG.

action Ação solicitada MarcarConsultado Sim

ids Listagem de ids dos processamentos a serem

marcados como consultados. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

2.2.3.5. Permissões

Permissões conforme cadastro de usuários:

- NFS-e Integrador (ROLE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

11

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

2.2.3.6. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- -

2.2.3.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids" com uma

lista de ids com RPSs a serem marcados.

Exemplo de Request Body conforme arquivo de exemplo:

nfse_request_post_marcar_consultado.txt

2.2.3.8. Retorno Sucesso

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

Http status: 200 (Solicitação enviada com sucesso)

2.2.3.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

2.2.4. ConsultarRpssAguardandoDownload:

2.2.4.1. Introdução

Método para consultar RPSs que estão com status de aguardando download no portal. Serão retornados

os arquivos que devem ser utilizados nos portais das prefeituras.

2.2.4.2. URL:

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

12

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

2.2.4.3. Exemplo URL:

http://localhost:8080/webservice/api/dfe (instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/dfe (ambiente de homologação do SaaS)

2.2.4.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG

action Ação solicitada ConsultarRpssAguardandoDownload Sim

referencia Informar referência da empresa a

ser consultada. "00910509000171_12345678" Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

2.2.4.5. Permissões

Permissões conforme cadastro de usuários:

- NFS-e Integrador (ROLE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

2.2.4.6. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- -

2.2.4.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "referencia" com

Exemplo de Request Body conforme arquivo de exemplo:

nfse_request_post_consultar_rpss_aguardando_download.txt

13

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

2.2.4.8. Retorno Sucesso

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

Http status: 200 (Solicitação enviada com sucesso)

2.2.4.8.1. Layout Retorno

CAMPO DESCRIÇÃO

formatoArquivo Formato do arquivo que está sendo retornado: TXT ou XML

body Conteúdo do arquivo.

result

Consultar arquivo de exemplo: nfse_response_post_consultar_rpss_aguardando_download.txt

2.2.4.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 400, 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

2.2.5. UploadRetornoPrefeitura:

2.2.5.1. Introdução

No campo referencia informar na estrutura: <CNPJ>_<IM>_<UF>_<MUNICIPIO>#<nome arquivo de

retorno>.xml

2.2.5.2. URL:

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

2.2.5.3. Exemplo URL:

http://localhost:8080/webservice/api/dfe (instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/dfe (ambiente de homologação do SaaS)

14

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

2.2.5.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG

action Ação solicitada UploadRetornoPrefeitura Sim

referencia

Informar:

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

>#<nome arquivo de retorno>.xml

"00910509000171_12345678_SC_JOINVI

LLE#joinville - rps 3

arquivo_retorno_prefeitura_joinville.xml"

Sim

txt_conteudo

Conteúdo do arquivo recebido da

prefeitura para ser atualizado no

software.

*Outras tags informadas não serão utilizadas, portanto, não as informe.

2.2.5.5. Permissões

Permissões conforme cadastro de usuários:

- NFS-e Integrador (ROLE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

2.2.5.6. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- -

2.2.5.7. Envio

O corpo do POST (request body) deve ser um json contendo todos os campos do layout do método.

Exemplo de Request Body conforme arquivo de exemplo:

nfse_request_post_upload_retorno_prefeitura.txt

15

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

2.2.5.8. Retorno Sucesso

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

Http status: 200 (Solicitação enviada com sucesso)

2.2.5.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 400, 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

2.2.6. Convertida:

2.2.6.1. Introdução

Método para consultar RPS já autorizados e que já foram marcadas como consultados.

2.2.6.2. URL:

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

2.2.6.3. Exemplo URL:

http://localhost:8080/webservice/api/dfe/convertida (instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/dfe/convertida (ambiente de homologação do SaaS)

2.2.6.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG

txt_conteudo Dados do RPS para consulta. Lista de campos que servirão de filtro

para o RPS. Sim

cnpjPrestador Atributo de txt_conteudo. CNPJ do

Prestador. Sim

inscricaoPrest

ador

Atributo de txt_conteudo.

Inscrição Municipal do Prestador. Sim

numeroRps Atributo de txt_conteudo. Numero Sim

16

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

do RPS.

serieRps Atributo de txt_conteudo. Série do

RPS. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

2.2.6.5. Permissões

Permissões conforme cadastro de usuários:

- NFS-e Integrador (ROLE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

2.2.6.6. Cabeçalho

Detalhes que devem ser informados na requisição:

- o usuário e

a senha fornecidos.

- -

2.2.6.7. Envio

O corpo do POST (request body) deve ser um json contendo todos os campos do layout do método.

Exemplo de Request Body conforme arquivo de exemplo: nfse_request_post_convertida.txt

2.2.6.8. Retorno Sucesso

Response Body: {"ids":[],"rpss":[]}

Http status: 200

2.2.6.8.1. Layout Retorno

CAMPO DESCRIÇÃO

ids Listagem dos IDs dos processamentos.

rpss Listagem dos RPSs.

17

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Os campos numéricos retornarão sem aspas, demais campos serão retornados entre .

Consultar arquivo de exemplo: nfse_response_convertida.txt

2.2.6.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 400, 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

2.3. MÉTODO: GET

2.3.1. Consulta Padrão

2.3.1.1. Introdução

Método para obter os retornos dos documentos enviados e a lista de documentos não consultados.

2.3.1.2. URL:

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

2.3.1.3. Filtro de Série e Quantidade de Resultados (maxResults):

Pode ser informado os parâmetros de Série NF-e e MaxResults para realizar a busca.

Quando não informada quantidade no parâmetro maxResults, será considerada a quantidade de 50

(cinquenta) results para cada consulta.

2.3.1.4. Exemplo URL:

http://localhost:8080/webservice/api/dfe (instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/dfe (ambiente de homologação do SaaS)

http://localhost:8080/webservice/api/dfe?maxResults=100&serie=001 (instalação in house)

Ou

18

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

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

SaaS)

2.3.1.5. Permissões

Permissões conforme cadastro de usuários:

- NFS-e Integrador (ROLE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

2.3.1.6. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

2.3.1.7. Envio

Nenhum dado além do cabeçalho deverá ser informado.

2.3.1.8. Retorno Sucesso

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

Http status: 200

2.3.1.8.1. Layout Retorno

CAMPO DESCRIÇÃO

retorno Conteúdo do retorno. Possui uma lista dos IDs dos

processamentos e uma listagens de seus respectivos RPSs.

ids Listagem dos IDs dos processamentos.

rpss Listagem dos RPSs.

No método GET, o resultado dos campos numéricos retornarão sem aspas, demais campos serão

.

19

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Consultar arquivo de exemplo: nfse_response_get.txt

2.3.1.9. Retorno Erro

Não há

3. MÓDULO NFE (MERCANTIL)

3.1. OBSERVAÇÕES GERAIS

Resumindo o processo, primeiramente é enviado um pacote de dados; depois é feita uma consulta

recebendo uma lista de ids e, então por fim, marcam-se no sistema os ids consultados para que numa

próxima consulta eles não sejam retornados novamente.

Para todos os requests é preciso usar basic authentication utilizando o usuário e a senha fornecidos.

Com isso basta realizar POST para enviar os pacotes e GET para consultar o resultado do

processamento. O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag

"txt_conteudo".

O txt_conteudo é formado por um objeto json, cujo atributo "xml" deve ser preenchido com o xml padrão

SEFAZ.

3.2. MÉTODO: POST

3.2.1. EnviarPacote:

3.2.1.1. Introdução

Método para envio de NF-es para serem autorizadas pela Sefaz correspondente.

3.2.1.2. URL:

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

3.2.1.3. Exemplo URL:

http://localhost:8080/webservice/api/nfe (instalação in house)

20

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

ou

https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologação do SaaS)

3.2.1.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG.

action Ação solicitada EnviarPacote Sim

referencia Nome do arquivo utilizado na integração. Não

txt_conteudo Grupo de informação da NF-e Sim

xml Conteúdo do XML de NF-e. Informar dados do

NF-e conforme layout padrão da Receita Federal. Sim

mastersaf Informações para contingência ou parâmetros

para filtro de impressão. Não

id_integrador Nome do integrador responsável pelo envio do

documento. Não

*Outras tags informadas não serão utilizadas, portanto, não as informe.

3.2.1.5. Permissões

Permissões conforme cadastro de usuários:

- NF-e Integrador (ROLE_NFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

3.2.1.6. Cabeçalho

Detalhes que devem ser informados na requisição:

- preciso usar basic authentication utilizando o usuário e

a senha fornecidos.

- -

3.2.1.7. Envio

O corpo do POST (request body) deve ser um json contendo todos os campos do layout do método.

Exemplo de Request Body conforme arquivo de exemplo: nfe_request_post_enviar_pacote_1.txt

21

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Caso necessite de contingencia na origem preencher o atributo "mastersaf", exemplo:

nfe_request_post_enviar_pacote_2.txt e nfe_request_post_enviar_pacote_3.txt

3.2.1.8. Retorno Sucesso

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

Http status: 202

3.2.1.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 400, 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

3.2.2. Cancelar

3.2.2.1. Introdução

Método para cancelar NF-es enviados ao webservice.

3.2.2.2. URL:

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

3.2.2.3. Exemplo URL:

http://localhost:8080/webservice/api/nfe (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologação do SaaS)

3.2.2.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG.

action Ação solicitada Sim

referencia Nome do arquivo de integração Não

txt_conteudo Grupo de informações de cancelamento. Sim

22

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

xml Conteúdo do Cancelamento de NF-e. Informar dados de

Cancelamento da NF-e conforme layout padrão do produto. Sim

id_integrador Nome do integrador responsável pelo envio do documento. Não

*Outras tags informadas não serão utilizadas, portanto, não as informe.

3.2.2.5. Permissões

Permissões conforme cadastro de usuários:

- NF-e Integrador (ROLE_NFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

3.2.2.6. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- -

3.2.2.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "txt_conteudo".

O txt_conteudo é posicional separado por ";"(ponto-e-virgula).

Exemplo de Request Body conforme arquivo de exemplo: nfe_request_post_cancelar.txt

3.2.2.8. Retorno Sucesso

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

Http status: 200 (Solicitação enviada com sucesso)

3.2.2.9. Retorno Erro

23

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Response Body: {"result":"<descrição do erro>"}

Http status: 400, 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

3.2.3. Inutilizar

3.2.3.1. Introdução

Método para inutilizar numerações de NF-es que ainda não foram utilizadas.

3.2.3.2. URL:

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

3.2.3.3. Exemplo URL:

http://localhost:8080/webservice/api/nfe (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologação do SaaS)

3.2.3.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG.

action Ação solicitada Sim

referencia Nome do arquivo de integração Não

txt_conteudo Grupo de informações de inutilização. Sim

xml Conteúdo da Inutilização de NF-e. Informar

dados conforme layout padrão do produto. Sim

id_integrador Nome do integrador responsável pelo envio

do documento. Não

*Outras tags informadas não serão utilizadas, portanto, não as informe.

3.2.3.5. Permissões

Permissões conforme cadastro de usuários:

- NF-e Integrador (ROLE_NFE_INTEGRADOR)

24

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

3.2.3.6. Cabeçalho

Detalhes que devem ser informados na requisição:

- dos os requests é preciso usar basic authentication utilizando o usuário e

a senha fornecidos.

- -

3.2.3.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "txt_conteudo".

O txt_conteudo é posicional separado por ";"(ponto-e-virgula).

Exemplo de Request Body conforme arquivo de exemplo: nfe_request_post_inutilizar.txt

3.2.3.8. Retorno Sucesso

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

Http status: 200 (Solicitação enviada com sucesso)

3.2.3.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 400, 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

3.2.4. EnviarCartaCorrecaoNfe

3.2.4.1. Introdução

Método para emitir cartas de correção para NF-es já autorizadas.

25

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

3.2.4.2. URL:

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

3.2.4.3. Exemplo URL:

http://localhost:8080/webservice/api/nfe (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologação do SaaS)

3.2.4.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG

action Ação solicitada Sim

referencia Nome do arquivo de integração Não

txt_conteudo Grupo de informações de carta de correção. Sim

xml

Conteúdo da Carta de Correção de NF-e.

Informar dados conforme layout padrão do

produto.

Sim

id_integrador Nome do integrador responsável pelo envio do

documento. Não

*Outras tags informadas não serão utilizadas, portanto, não as informe.

3.2.4.5. Permissões

Permissões conforme cadastro de usuários:

- NF-e Integrador (ROLE_NFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

3.2.4.6. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

26

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

- -

3.2.4.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "txt_conteudo".

O txt_conteudo é posicional separado por ";"(ponto-e-virgula).

Exemplo de Request Body conforme arquivo de exemplo:

nfe_request_post_enviar_carta_correcao_nfe.txt

3.2.4.8. Retorno Sucesso

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

Http status: 200 (Solicitação enviada com sucesso)

3.2.4.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 400, 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

3.2.5. MarcarConsultado

3.2.5.1. Introdução

Método para indicar ao WebService que determinados documentos já foram consultados e não precisam

mais ser retornados na consulta (GET).

Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de

retorno.

3.2.5.2. URL:

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

3.2.5.3. Exemplo URL:

http://localhost:8080/webservice/api/nfe (instalação in house)

27

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

ou

https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologação do SaaS)

3.2.5.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG.

action Ação solicitada MarcarConsultado Sim

ids Listagem de ids dos processamentos a serem

marcados como consultados. Sim

id_integrador Nome do integrador responsável pelo envio

do documento. Não

*Outras tags informadas não serão utilizadas, portanto, não as informe.

3.2.5.5. Permissões

Permissões conforme cadastro de usuários:

- NF-e Integrador (ROLE_NFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

3.2.5.6. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- -

3.2.5.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids".

Exemplo de Request Body conforme arquivo de exemplo: nfe_request_post_marcar_consultado.txt

3.2.5.8. Retorno Sucesso

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

28

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Http status: 200 (Solicitação enviada com sucesso)

3.2.5.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

3.2.6. MarcarImpresso

3.2.6.1. Introdução

Método para indicar ao WebService que determinados documentos já foram impressos e não precisam

mais ser retornados na consulta (GET).

Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de

retorno.

3.2.6.2. URL:

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

3.2.6.3. Exemplo URL:

http://localhost:8080/webservice/api/nfe (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologação do SaaS)

3.2.6.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG

action Ação solicitada Sim

ids Grupo de informações para marcar como impresso. Sim

idProcessamento Id do processamento a ser marcado. Sim

idNota Id da nota a ser marcada. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

29

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

3.2.6.5. Permissões

Permissões conforme cadastro de usuários:

- NF-e Integrador (ROLE_NFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

3.2.6.6. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- -

3.2.6.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids".

Exemplo de Request Body conforme arquivo de exemplo: nfe_request_post_marcar_impresso.txt

3.2.6.8. Retorno Sucesso

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

Http status: 200 (Solicitação enviada com sucesso)

3.2.6.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

3.2.7. MarcarCartaCorrecaoImpresso

3.2.7.1. Introdução

30

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Método para indicar ao WebService que determinados Cartas de Correção já foram impressos e não

precisam mais ser retornados na consulta (GET).

Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de

retorno.

3.2.7.2. URL:

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

3.2.7.3. Exemplo URL:

http://localhost:8080/webservice/api/nfe (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologação do SaaS)

3.2.7.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG

Action Ação solicitada MarcarCartaCorrecaoImpresso Sim

Ids Grupo de informações para marcar

como impresso. Sim

idProcessamento Id do processamento a ser marcado. Sim

idNota Id da CCe a ser marcada. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

3.2.7.5. Permissões

Permissões conforme cadastro de usuários:

- NF-e Integrador (ROLE_NFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

3.2.7.6. Cabeçalho

Detalhes que devem ser informados na requisição:

31

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

-

a senha fornecidos.

- -

3.2.7.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids".

Exemplo de Request Body conforme arquivo de exemplo:

nfe_request_post_marcar_carta_correcao_impresso.txt

3.2.7.8. Retorno Sucesso

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

Http status: 200 (Solicitação enviada com sucesso)

3.2.7.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

3.2.8. ReimpressaoDanfe

3.2.8.1. Introdução

Método para solicitar reimpressão de NF-es.

3.2.8.2. URL:

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

3.2.8.3. Exemplo URL:

http://localhost:8080/webservice/api/nfe (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologação do SaaS)

32

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

3.2.8.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG

action Ação solicitada ReimpressaoDanfe Sim

txt_conteudo Grupo de informações de reimpressão. Sim

xml Conteúdo da solicitação de Reimpressão de NF-e.

Informar dados conforme layout padrão do produto. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

3.2.8.5. Permissões

Permissões conforme cadastro de usuários:

- NF-e Integrador (ROLE_NFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

3.2.8.6. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- -

3.2.8.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "txt_conteudo".

O txt_conteudo é posicional separado por ";"(ponto-e-virgula).

Exemplo de Request Body conforme arquivo de exemplo: nfe_request_post_reimpressao_danfe.txt

3.2.8.8. Retorno Sucesso

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

33

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Http status: 200 (Solicitação enviada com sucesso)

3.2.8.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 400, 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

3.2.9. Consultar Cadastro

3.2.9.1. Introdução

Método para envio de Consultas de Cadastros pela Sefaz correspondente.

3.2.9.2. URL:

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

3.2.9.3. Exemplo URL:

http://localhost:8080/webservice/api/nfe (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologação do SaaS)

3.2.9.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG

action Ação solicitada Sim

referencia Nome do arquivo utilizado na integração. Não

txt_conteudo Grupo de informação da consulta. Sim

xml Conteúdo da Consulta do Cadastro conforme layout padrão

do produto. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

3.2.9.4.1. Detalhamento campo XML

CAMPO DESCRIÇÃO CONTEÚDO TIPO TAMANHO

--consulta_cadastro_ini--

versao Versão do Layout 2.00 Caractere 4

34

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

CNPJ CNPJ da empresa. Identificação da empresa

para o qual será

retornado a consulta.

Caractere 14

IE Inscrição Estadual da

empresa. Caractere

0-14

UF_pesquisa UF à qual se destina a

consulta. Caractere

2

IE_pesquisa Inscrição Estadual a ser

consultada. Somente um dos campos

deve ser preenchido.

Caractere 0-14

CNPJ_pesquisa CNPJ a ser consultado. Caractere 14

CPF_pesquisa CPF a ser consultado. Caractere 11

--consulta_cadastro_fim--

--arquivo_fim--

3.2.9.5. Permissões

Permissões conforme cadastro de usuários:

- NF-e Integrador (ROLE_NFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

3.2.9.6. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- -

3.2.9.7. Envio

O corpo do POST (request body) deve ser um json contendo todos os campos do layout do método.

3.2.9.8. Retorno Sucesso

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

Http status: 202

35

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

3.2.9.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 400, 412, 500.

3.3. MÉTODO: GET

3.3.1. Consulta Padrão:

3.3.1.1. Introdução

Método para obter os retornos dos documentos enviados, lista de documentos não consultados, dados

de lotes inutilizados, dados de cartas de correção emitidas e os documentos que devem ser enviados

para o Printer imprimir.

3.3.1.2. URL:

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

3.3.1.3. Definir quantidade de Results da consulta:

<host>:<port>/<webservice>/api/nfe?maxResults=

Quando informada quantidade no parâmetro, será considerada a quantidade máxima de results para

cada lista e grupo de retorno (impressao[], impressaoCce[], retorno{...}).

Quando não informada quantidade no parâmetro, será considerada a quantidade de 50 (cinquenta)

results para cada lista e grupo de retorno (impressao[], impressaoCce[], retorno{...}).

3.3.1.4. Exemplo URL:

http://localhost:8080/webservice/api/nfe (instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/nfe (ambiente de homologação do SaaS)

http://localhost:8080/webservice/api/nfe?maxResults=100 (instalação in house)

Ou

36

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

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

3.3.1.5. Permissões

Permissões conforme cadastro de usuários:

- NF-e Integrador (ROLE_NFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

3.3.1.6. Cabeçalho

Detalhes que devem ser informados na requisição:

- uário e

a senha fornecidos.

3.3.1.7. Envio

Nenhum dado além do cabeçalho deverá ser informado.

3.3.1.8. Retorno Sucesso

Response Body:

{

"impressao": [],

"impressaoCCe": [],

"retorno": {

"loteCartaCorrecao": [],

"consultaCadastro": [],

"nfes": [],

"ids": [],

"loteInutilizado": []

}

} Http status: 200

37

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

3.3.1.8.1. Layout Retorno

CAMPO DESCRIÇÃO

Impressao Lista documentos para impressão.

impressaoCce Lista documentos de Carta de Correção para impressão.

idProcessamento processamento.

params

retorno Grupo de informações para geração dos arquivos de retorno.

ids Listagem dos IDs dos processamentos que constam

como não consultados.

nfes Atributo de Listagem dos retornos das NF-es que foram processadas

pelo software.

loteCartaCorrecao Listagem dos retornos das Cartas de Correção enviadas.

loteInutilizado Inutilizações enviadas.

consultaCadastro

Detalhamento de campos específicos do Layout Retorno

CAMPO DESCRIÇÃO

nfes.nota.urlDanfePortal

Disponibilizamos o link para abertura do DANFE.

Este novo campo deverá ser preenchido somente nos retornos em que o status de

NF-e permita a impressão de DANFE (Autorizada ou Cancelada).

Para funcionamento da geração do link do DANFE, o preenchimento do campo “URL

de acesso ao portal” da tela Administração do Sistema > Extrato do Sistema torna-se

obrigatório.

Para a visualização do DANFE o usuário deverá ter a permissão “NF-e Visualizar”

habilitada em seu perfil.

Exemplo:

nfes":[{"nota":{"urlDanfePortal":"https://h.dfe.mastersaf.com.br/mvc/nfe/pdf/visualizar

Danfe/12345",

Consultar arquivo de exemplo: nfe_response_get.txt e nfe_response_get_cadastro.txt

3.3.1.9. Retorno Erro

38

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Não há

3.3.2. GetXml

3.3.2.1. Introdução

Método para obter o XML processado da respectiva chave de NF-e.

3.3.2.2. URL:

<host>:<port>/<webservice>/api/nfe/<chave nfe>/getXml

3.3.2.3. Exemplo URL:

http://localhost:8080/webservice/api/nfe/<chave nfe>/getXml

(instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/nfe/<chave nfe>/getXml

(ambiente de homologação do SaaS)

3.3.2.4. Permissões

Permissões conforme cadastro de usuários:

- NF-e Integrador (ROLE_NFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

3.3.2.5. Cabeçalho

Detalhes que devem ser informados na requisição:

- é preciso usar basic authentication utilizando o usuário e

a senha fornecidos.

- - -8859- Para o xml retornar com a codificação

correta.

39

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

3.3.2.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

3.3.2.7. Retorno Sucesso

Response Body: XML processado.

Http status: 200

Consultar arquivo de exemplo: nfe_response_get_xml.txt

3.3.2.8. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 203, 404, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

3.3.3. GetXmlCancelamento

3.3.3.1. Introdução

Método para obter o XML cancelado da respectiva chave de NF-e.

3.3.3.2. URL:

<host>:<port>/<webservice>/api/nfe/<chave nfe>/getXmlCancelamento

3.3.3.3. Exemplo URL:

http://localhost:8080/webservice/api/nfe/<chave nfe>/getXmlCancelamento

(instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/nfe/<chave nfe>/getXmlCancelamento

(ambiente de homologação do SaaS)

3.3.3.4. Permissões

40

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Permissões conforme cadastro de usuários:

- NF-e Integrador (ROLE_NFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

3.3.3.5. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- - -8859- Para o xml retornar com a codificação

correta.

3.3.3.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

3.3.3.7. Retorno Sucesso

Response Body: XML de cancelamento processado.

Http status: 200

Consultar arquivo de exemplo: nfe_response_get_xml_cancelado.txt

3.3.3.8. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 203, 404, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

3.3.4. GetDanfe

3.3.4.1. Introdução

Método para obter o DANFE da respectiva chave de NF-e.

41

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

3.3.4.2. URL:

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

3.3.4.3. Exemplo URL:

http://localhost:8080/webservice/api/nfe/<chave nfe>/getDanfe

(instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/nfe/<chave nfe>/getDanfe

(ambiente de homologação do SaaS)

3.3.4.4. Permissões

Permissões conforme cadastro de usuários:

- NF-e Integrador (ROLE_NFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

3.3.4.5. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

3.3.4.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

3.3.4.7. Retorno Sucesso

Response Body: retornará um array de bytes (byte[]). Esse retorno terá de ser escrito em disco com

Http status: 200

42

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

3.3.4.8. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 203, 404, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

3.3.5. GetStatus

3.3.5.1. Introdução

Método para obter o Status (Código-Descrição) da respectiva chave de NF-e.

3.3.5.2. URL:

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

3.3.5.3. Exemplo URL:

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

(instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/nfe/<chave nfe>/ getStatus

(ambiente de homologação do SaaS)

3.3.5.4. Permissões

Permissões conforme cadastro de usuários:

- NF-e Integrador (ROLE_NFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

3.3.5.5. Cabeçalho

Detalhes que devem ser informados na requisição:

43

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

- requests é preciso usar basic authentication utilizando o usuário e

a senha fornecidos.

3.3.5.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

3.3.5.7. Retorno Sucesso

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

Http status: 200

3.3.5.8. Layout Retorno

CAMPO DESCRIÇÃO

retorno Grupo de informações para geração dos arquivos de retorno.

ids não consultados.

nfes -es que foram processadas

pelo software.

loteCartaCorrecao

loteInutilizado nutilizações enviadas.

3.3.5.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 203, 404, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

3.3.6. GetStatus (com parâmetros)

3.3.6.1. Introdução

Método para obter o Status (Código-Descrição) de NF-e apartir de um conjunto de filtros.

3.3.6.2. URL:

44

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

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

3.3.6.3. Filtro de CNPJ Emissor, Número da NF-e e Série da NF-e:

É necessário informar os parâmetros de CNPJ Emissor, Número NF-e e Série NF-e para realizar a busca.

Todos os parâmetros são obrigatórios.

3.3.6.4. Exemplo URL:

http://localhost:8080/webservice/api/nfe/getStatus?cnpjEmissor=1234567890&numeroNfe=1000&ser

ie=730

(instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/nfe/getStatus?cnpjEmissor=1234567890&numeroNfe=1000&se

rie=730

(ambiente de homologação do SaaS)

3.3.6.5. Permissões

Permissões conforme cadastro de usuários:

- NF-e Integrador (ROLE_NFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

3.3.6.6. Cabeçalho

Detalhes que devem ser informados na requisição:

- o usuário e

a senha fornecidos.

3.3.6.7. Envio

Nenhum dado além do cabeçalho deverá ser informado.

45

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

3.3.6.8. Retorno Sucesso

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

Http status: 200

3.3.6.9. Layout Retorno

CAMPO DESCRIÇÃO

retorno Grupo de informações para geração dos arquivos de retorno.

ids não consultados.

nfes -es que foram processadas

pelo software.

loteCartaCorrecao

loteInutilizado

3.3.6.10. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 203, 404, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

3.3.7. Consulta Retorno:

3.3.7.1. Introdução

Método para obter os retornos dos documentos enviados, lista de documentos não consultados, dados

de lotes inutilizados e dados de cartas de correção.

3.3.7.2. URL:

<host>:<port>/<webservice>/api/nfe/getRetorno

3.3.7.3. Definir quantidade de Results da consulta:

<host>:<port>/<webservice>/api/nfe/getRetorno?maxResults=

46

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Quando não informada quantidade no parâmetro, será considerada a quantidade de 50 (cinquenta)

results para cada consulta.

3.3.7.4. Filtro de Série

Para filtrar a consulta pela série, a mesma deverá ser enviada na URL. Se houver mais de uma, separá-

las por vírgula.

3.3.7.5. Exemplo URL com filtro:

http://localhost:8085/webservice/api/nfe/getRetorno/serie=700

Ou

http://localhost:8085/webservice/api/nfe/getRetorno/serie=700,701,703

http://localhost:8085/webservice/api/nfe/getRetorno/serie=700?maxResults=100

Ou

http://localhost:8085/webservice/api/nfe/getRetorno/serie=700,701,703?maxResults=100

3.3.7.6. Exemplo URL sem filtro:

http://localhost:8080/webservice/api/nfe/getRetorno (instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/nfe/getRetorno (ambiente de homologação do SaaS)

http://localhost:8080/webservice/api/nfe/getRetorno?maxResults=100 (instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/nfe/getRetorno?maxResults=100 (ambiente de homologação do

SaaS)

3.3.7.7. Permissões

Permissões conforme cadastro de usuários:

- NF-e Integrador (ROLE_NFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

47

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

3.3.7.8. Cabeçalho

Detalhes que devem ser informados na requisição:

- utilizando o usuário e

a senha fornecidos.

3.3.7.9. Envio

Nenhum dado além do cabeçalho deverá ser informado.

3.3.7.10. Retorno Sucesso

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

Http status: 200

3.3.7.10.1. Layout Retorno

CAMPO DESCRIÇÃO

retorno Grupo de informações para geração dos arquivos de retorno.

ids não consultados.

nfes -es que foram processadas

pelo software.

loteCartaCorrecao

loteInutilizado

Consultar arquivo de exemplo: nfe_response_getRetorno.txt

3.3.7.11. Retorno Erro

Não há

3.3.8. Consulta Impressão:

3.3.8.1. Introdução

48

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Método para obter os retornos dos documentos que devem ser enviados para o Printer imprimir.

3.3.8.2. URL:

<host>:<port>/<webservice>/api/nfe/getImpressao

3.3.8.3. Exemplo URL:

http://localhost:8080/webservice/api/nfe/getImpressao (instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/nfe/getImpressao (ambiente de homologação do SaaS)

3.3.8.4. Permissões

Permissões conforme cadastro de usuários:

- NF-e Integrador (ROLE_NFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

3.3.8.5. Cabeçalho

Detalhes que devem ser informados na requisição:

- é preciso usar basic authentication utilizando o usuário e

a senha fornecidos.

3.3.8.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

3.3.8.7. Retorno Sucesso

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

Http status: 200

49

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

3.3.8.7.1. Layout Retorno

CAMPO DESCRIÇÃO

impressao Lista documentos para impressão.

impressaoCCe Lista de eventos de carta de correção para impressão.

idProcessamento

params

Consultar arquivo de exemplo: nfe_response_getImpressao.txt

3.3.8.8. Retorno Erro

Não há

3.3.9. Consulta Impressão NFe:

3.3.9.1. Introdução

Método para obter apenas os retornos dos documentos de NF-e que devem ser enviados para o Printer

imprimir. Após o retorno, o sistema marca os documentos como

não são mais retornados pelo método.

3.3.9.2. URL:

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

3.3.9.3. Exemplo URL:

http://localhost:8080/webservice/api/nfe/getImpressaoNfe (instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/nfe/getImpressaoNfe(ambiente de homologação do SaaS)

3.3.9.4. Permissões

Permissões conforme cadastro de usuários:

- NF-e Integrador (ROLE_NFE_INTEGRADOR)

50

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

3.3.9.5. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

3.3.9.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

3.3.9.7. Retorno Sucesso

Response Body: {"impressao":[]}

Http status: 200

3.3.9.7.1. Layout Retorno

CAMPO DESCRIÇÃO

impressao Lista documentos para impressão.

idProcessamento

params

Consultar arquivo de exemplo: nfe_response_getImpressaoNfe.txt

3.3.9.8. Retorno Erro

Não há

3.3.10. Consulta Impressão Carta Correção NFe:

3.3.10.1. Introdução

51

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Método para obter apenas os retornos dos documentos de CC NF-e que devem ser enviados para o

Printer imprimir.

impressã

3.3.10.2. URL:

<host>:<port>/<webservice>/api/nfe/getImpressaoCcNfe

3.3.10.3. Exemplo URL:

http://localhost:8080/webservice/api/nfe/getImpressaoCcNfe (instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/nfe/getImpressaoCcNfe(ambiente de homologação do SaaS)

3.3.10.4. Permissões

Permissões conforme cadastro de usuários:

- NF-e Integrador (ROLE_NFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

3.3.10.5. Cabeçalho

Detalhes que devem ser informados na requisição:

- usar basic authentication utilizando o usuário e

a senha fornecidos.

3.3.10.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

3.3.10.7. Retorno Sucesso

Response Body: {"impressao":[]}

Http status: 200

52

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

3.3.10.7.1. Layout Retorno

CAMPO DESCRIÇÃO

impressaoCCe Lista de eventos de carta de correção para impressão.

idProcessamento

params

Consultar arquivo de exemplo: nfe_response_getImpressaoCcNfe.txt

3.3.10.8. Retorno Erro

Não há

4. MÓDULO CTE

4.1. OBSERVAÇÕES GERAIS

Resumindo o processo, primeiramente é enviado um pacote de dados; depois é feita uma consulta

recebendo uma lista de ids e, então por fim, marcam-se no sistema os ids consultados para que numa

próxima consulta eles não sejam retornados novamente, também são retornados os CT-es para

impressão via printer.

Para todos os requests é preciso usar basic authentication utilizando o usuário e a senha fornecidos.

Com isso basta realizar POST para enviar os pacotes e GET para consultar o resultado do

processamento. O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag

"txt_conteudo".

O separador de campos do conteúdo é o pipe ( | ). Para quebra de linha usa-se \n.

Para enviar vários CT-es você deve concatenar as strings antes de colocar em txt_conteúdo (txt conteúdo

terá vários "{"config": " .. ", "xml" : "..."} separando-os por vírgula. No caso de cancelamento e

inutilização o procedimento é o mesmo.

4.2. MÉTODO: POST

53

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

4.2.1. EnviarPacote:

4.2.1.1. Introdução

Método para envio de CT-es para serem autorizadas pela Sefaz correspondente.

4.2.1.2. URL:

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

4.2.1.3. Exemplo URL:

http://localhost:8080/webservice/api/cte (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologação do SaaS)

4.2.1.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG

action Ação solicitada Sim

referencia Nome do arquivo utilizado na integração. Não

txt_conteudo Grupo de informações do CT-e Sim

xml Conteúdo do XML de CT-e. Informar dados conforme

layout padrão da Receita Federal. Sim

config Configurações. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

4.2.1.5. Permissões

Permissões conforme cadastro de usuários:

- CT-e Integrador (ROLE_CTE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

4.2.1.6. Cabeçalho

54

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- - application/json

4.2.1.7. Envio

O corpo do POST (request body) deve ser um json contendo todos os campos do layout do método.

Exemplo de Request Body conforme arquivo de exemplo: cte_request_post_enviar_pacote.txt

4.2.1.8. Retorno Sucesso

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

Http status: 202

4.2.1.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 400, 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

4.2.2. Cancelar

4.2.2.1. Introdução

Método para cancelar CT-es enviados ao webservice.

4.2.2.2. URL:

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

4.2.2.3. Exemplo URL:

http://localhost:8080/webservice/api/cte (instalação in house)

ou

55

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologação do SaaS)

4.2.2.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG.

action Ação solicitada Sim

referencia Nome do arquivo de integração Não

txt_conteudo Grupo de informações de cancelamento. Sim

xml Conteúdo do Cancelamento de CT-e. Informar dados

conforme layout padrão da Receita Federal. Sim

config Configurações. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

4.2.2.5. Permissões

Permissões conforme cadastro de usuários:

- CT-e Integrador (ROLE_CTE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

4.2.2.6. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- -

4.2.2.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "txt_conteudo".

Exemplo de Request Body conforme arquivo de exemplo: cte_request_post_cancelar.txt

4.2.2.8. Retorno Sucesso

56

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

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

Http status: 200 (Solicitação enviada com sucesso)

4.2.2.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 400, 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

4.2.3. EnviarCartaCorrecaoCte

4.2.3.1. Introdução

Método para emitir cartas de correção para CT-es já autorizadas.

4.2.3.2. URL:

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

4.2.3.3. Exemplo URL:

http://localhost:8080/webservice/api/cte (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologação do SaaS)

4.2.3.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG

action Ação solicitada Sim

referencia Nome do arquivo de integração Não

txt_conteudo Grupo de informações de carta de correção. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

4.2.3.5. Permissões

Permissões conforme cadastro de usuários:

57

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

- NF-e Integrador (ROLE_CTE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

- CT-e Carta Correção (ROLE_CTE_CARTA_CORRECAO)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

4.2.3.6. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- -

4.2.3.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "txt_conteudo".

O txt_conteudo é posicional separado por ";"(ponto-e-virgula).

Exemplo de Request Body conforme arquivo de exemplo:

cte_request_post_carta_correcao.txt

4.2.3.8. Retorno Sucesso

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

Http status: 200 (Solicitação enviada com sucesso)

4.2.3.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 400, 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

4.2.4. Inutilizar

4.2.4.1. Introdução

58

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Método para inutilizar numerações de CT-es que ainda não foram utilizadas.

4.2.4.2. URL:

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

4.2.4.3. Exemplo URL:

http://localhost:8080/webservice/api/cte (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologação do SaaS)

4.2.4.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG.

action Ação solicitada Sim

referencia Nome do arquivo de integração Não

txt_conteudo Grupo de informações de inutilização. Sim

xml Conteúdo da Inutilização de CT-e. Informar dados

conforme layout padrão da Receita Federal. Sim

config Configurações. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

4.2.4.5. Permissões

Permissões conforme cadastro de usuários:

- CT-e Integrador (ROLE_CTE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

4.2.4.6. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

59

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

- -

4.2.4.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "txt_conteudo".

Exemplo de Request Body conforme arquivo de exemplo: cte_request_post_inutilizar.txt

4.2.4.8. Retorno Sucesso

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

Http status: 200 (Solicitação enviada com sucesso)

4.2.4.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 400, 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

4.2.5. MarcarConsultado

4.2.5.1. Introdução

Método para indicar ao WebService que determinados documentos já foram consultados e não precisam

mais ser retornados na consulta (GET).

Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de

retorno.

4.2.5.2. URL:

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

4.2.5.3. Exemplo URL:

http://localhost:8080/webservice/api/cte (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologação do SaaS)

60

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

4.2.5.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG

action Ação solicitada Sim

ids Listagem de ids dos processamentos a serem marcados

como consultados. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

4.2.5.5. Permissões

Permissões conforme cadastro de usuários:

- CT-e Integrador (ROLE_CTE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

4.2.5.6. Cabeçalho

Detalhes que devem ser informados na requisição:

- odos os requests é preciso usar basic authentication utilizando o usuário e

a senha fornecidos.

- -

4.2.5.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids".

Exemplo de Request Body conforme arquivo de exemplo: cte_request_post_marcar_consultado.txt

4.2.5.8. Retorno Sucesso

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

Http status: 200 (Solicitação enviada com sucesso)

4.2.5.9. Retorno Erro

61

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Response Body: {"result":"<descrição do erro>"}

Http status: 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

4.2.6. MarcarImpresso

4.2.6.1. Introdução

Método para indicar ao WebService que determinados documentos já foram impressos e não precisam

mais ser retornados na consulta (GET).

Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de

retorno.

4.2.6.2. URL:

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

4.2.6.3. Exemplo URL:

http://localhost:8080/webservice/api/cte (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologação do SaaS)

4.2.6.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG

action Ação solicitada Sim

ids Grupo de informações para marcar como impresso. Sim

idProcessamento Id do processamento a ser marcado. Sim

idNota Id da nota a ser marcada. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

4.2.6.5. Permissões

Permissões conforme cadastro de usuários:

- CT-e Integrador (ROLE_CTE_INTEGRADOR)

62

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

4.2.6.6. Cabeçalho

Detalhes que devem ser informados na requisição:

- utilizando o usuário e

a senha fornecidos.

- -

4.2.6.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids".

Exemplo de Request Body conforme arquivo de exemplo: cte_request_post_marcar_impresso.txt

4.2.6.8. Retorno Sucesso

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

Http status: 200 (Solicitação enviada com sucesso)

4.2.6.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

4.2.7. MarcarCartaCorrecaoImpresso

4.2.7.1. Introdução

Método para indicar ao WebService que determinadas Cartas de Correção já foram impressos e não

precisam mais ser retornados na consulta (GET).

Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de

retorno.

63

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

4.2.7.2. URL:

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

4.2.7.3. Exemplo URL:

http://localhost:8080/webservice/api/cte (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologação do SaaS)

4.2.7.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG

action Ação solicitada CartaCorrecaoImpresso Sim

ids Grupo de informações para marcar

como impresso. Sim

idProcessamento Id do processamento a ser marcado. Sim

idNota Id da CCe a ser marcada. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

4.2.7.5. Permissões

Permissões conforme cadastro de usuários:

- CT-e Integrador (ROLE_CTE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

4.2.7.6. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- -

64

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

4.2.7.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids".

Exemplo de Request Body conforme arquivo de exemplo:

cte_request_post_marcar_carta_correcao_impresso.txt

4.2.7.8. Retorno Sucesso

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

Http status: 200 (Solicitação enviada com sucesso)

4.2.7.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

4.3. MÉTODO: GET

4.3.1. Consulta Padrão

4.3.1.1. Introdução

Método para obter os retornos dos documentos enviados, lista de documentos não consultados, dados

de lotes inutilizados e os documentos que devem ser enviados para o Printer imprimir.

4.3.1.2. URL:

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

4.3.1.3. Definir quantidade de Results da consulta:

<host>:<port>/<webservice>/api/cte?maxResults=

Quando informada quantidade no parâmetro, será considerada a quantidade máxima de results para

cada lista e grupo de retorno (impressao[], retorno{...}).

65

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Quando não informada quantidade no parâmetro, será considerada a quantidade de 50 (cinquenta)

results para cada lista e grupo de retorno (impressao[], retorno{...}).

4.3.1.4. Exemplo URL:

http://localhost:8080/webservice/api/cte (instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/cte (ambiente de homologação do SaaS)

http://localhost:8080/webservice/api/cte?maxResults=100 (instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/cte?maxResults=100 (ambiente de homologação do SaaS)

4.3.1.5. Permissões

Permissões conforme cadastro de usuários:

- CT-e Integrador (ROLE_CTE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

4.3.1.6. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

4.3.1.7. Envio

Nenhum dado além do cabeçalho deverá ser informado.

4.3.1.8. Retorno Sucesso

Response Body:

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

66

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Http status: 200

4.3.1.8.1. Layout Retorno

CAMPO DESCRIÇÃO

impressao Lista documentos para impressão.

id

nota Atribu .

retorno Grupo de informações para geração dos arquivos de retorno.

ids tam como não

consultados.

ctes CT-es que foram processadas pelo

software.

loteInutilizado

Consultar arquivo de exemplo: cte_response_get.txt

4.3.1.9. Retorno Erro

Não há

4.3.2. GetXml

4.3.2.1. Introdução

Método para obter o XML processado da respectiva chave de CT-e.

4.3.2.2. URL:

<host>:<port>/<webservice>/api/cte/<chave cte>/getXml

4.3.2.3. Exemplo URL:

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

(instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/cte/<chave cte>/getXml

67

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

(ambiente de homologação do SaaS)

4.3.2.4. Permissões

Permissões conforme cadastro de usuários:

- CT-e Integrador (ROLE_CTE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

4.3.2.5. Cabeçalho

Detalhes que devem ser informados na requisição:

- usuário e

a senha fornecidos.

- - -8859- Para o xml retornar com a codificação

correta.

4.3.2.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

4.3.2.7. Retorno Sucesso

Response Body: XML processado.

Http status: 200

Consultar arquivo de exemplo: cte_response_get_xml.txt

4.3.2.8. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 203, 404, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

68

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

4.3.3. GetXmlCancelamento

4.3.3.1. Introdução

Método para obter o XML cancelado da respectiva chave de CT-e.

4.3.3.2. URL:

<host>:<port>/<webservice>/api/cte/<chave cte>/getXmlCancelamento

4.3.3.3. Exemplo URL:

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

(instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/cte/<chave cte>/getXmlCancelamento

(ambiente de homologação do SaaS)

4.3.3.4. Permissões

Permissões conforme cadastro de usuários:

- CT-e Integrador (ROLE_CTE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

4.3.3.5. Cabeçalho

Detalhes que devem ser informados na requisição:

- odos os requests é preciso usar basic authentication utilizando o usuário e

a senha fornecidos.

- - -8859- Para o xml retornar com a codificação

correta.

4.3.3.6. Envio

69

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Nenhum dado além do cabeçalho deverá ser informado.

4.3.3.7. Retorno Sucesso

Response Body: XML de cancelamento processado.

Http status: 200

Consultar arquivo de exemplo: cte_response_get_xml_cancelamento.txt

4.3.3.8. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 203, 404, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

4.3.4. GetDacte

4.3.4.1. Introdução

Método para obter o DACTE da respectiva chave de CT-e.

4.3.4.2. URL:

<host>:<port>/<webservice>/api/cte/<chave cte>/getDacte

4.3.4.3. Exemplo URL:

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

(instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/cte/<chave cte>/getDacte

(ambiente de homologação do SaaS)

4.3.4.4. Permissões

Permissões conforme cadastro de usuários:

70

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

- CT-e Integrador (ROLE_CTE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

4.3.4.5. Cabeçalho

Detalhes que devem ser informados na requisição:

- todos os requests é preciso usar basic authentication utilizando o usuário e

a senha fornecidos.

4.3.4.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

4.3.4.7. Retorno Sucesso

Response Body: retornará um array de bytes (byte[]). Esse retorno terá de ser escrito em disco com

Http status: 200

4.3.4.8. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 203, 404, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

4.3.5. GetStatus

4.3.5.1. Introdução

Método para obter o STATUS da respectiva chave de CT-e.

4.3.5.2. URL:

host>:<port>/<webservice>/api/cte/<chave cte>/getStatus

71

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

4.3.5.3. Exemplo URL:

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

(instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/cte/<chave cte>/ getStatus

(ambiente de homologação do SaaS)

4.3.5.4. Permissões

Permissões conforme cadastro de usuários:

- CT-e Integrador (ROLE_CTE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

4.3.5.5. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

4.3.5.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

4.3.5.7. Retorno Sucesso

Http status: 200

4.3.5.8. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 203, 404, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

72

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

4.3.6. Consulta Retorno

4.3.6.1. Introdução

Método para obter os retornos dos documentos enviados, lista de documentos não consultados e dados

de lotes inutilizados.

4.3.6.2. URL:

<host>:<port>/<webservice>/api/cte/getRetorno

4.3.6.3. Definir quantidade de Results da consulta:

<host>:<port>/<webservice>/api/cte/getRetorno?maxResults=

Quando não informada quantidade no parâmetro, será considerada a quantidade de 50 (cinquenta)

results para cada consulta.

4.3.6.4. Filtro de Série

Para filtrar a consulta pela série, a mesma deverá ser enviada na URL. Se houver mais de uma, separá-

las por vírgula.

4.3.6.5. Exemplo URL com filtro:

http://localhost:8085/webservice/api/cte/getRetorno/serie=700

Ou

http://localhost:8085/webservice/api/cte/getRetorno/serie=700,701,703

http://localhost:8085/webservice/api/cte/getRetorno/serie=700?maxResults=100

Ou

http://localhost:8085/webservice/api/cte/getRetorno/serie=700,701,703?maxResults=100

4.3.6.6. Exemplo URL sem filtro:

http://localhost:8080/webservice/api/cte/getRetorno (instalação in house)

Ou

73

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

https://ws.h.dfe.mastersaf.com.br/api/cte/getRetorno (ambiente de homologação do SaaS)

4.3.6.7. Permissões

Permissões conforme cadastro de usuários:

- CT-e Integrador (ROLE_CTE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

4.3.6.8. Cabeçalho

Detalhes que devem ser informados na requisição:

- usar basic authentication utilizando o usuário e

a senha fornecidos.

4.3.6.9. Envio

Nenhum dado além do cabeçalho deverá ser informado.

4.3.6.10. Retorno Sucesso

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

Http status: 200

4.3.6.10.1. Layout Retorno

CAMPO DESCRIÇÃO

retorno Grupo de informações para geração dos arquivos de retorno.

ids consultados.

ctes CT-es que foram processadas pelo

software.

loteInutilizado

Consultar arquivo de exemplo: cte_response_getRetorno.txt

74

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

4.3.6.11. Retorno Erro

Não há

4.3.7. Consulta Impressão

4.3.7.1. Introdução

Método para obter os retornos dos documentos que devem ser enviados para o Printer imprimir.

4.3.7.2. URL:

<host>:<port>/<webservice>/api/cte/getImpressao

4.3.7.3. Exemplo URL:

http://localhost:8080/webservice/api/cte/getImpressao (instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/cte/getImpressao (ambiente de homologação do SaaS)

4.3.7.4. Permissões

Permissões conforme cadastro de usuários:

- CT-e Integrador (ROLE_CTE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

4.3.7.5. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

4.3.7.6. Envio

75

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Nenhum dado além do cabeçalho deverá ser informado.

4.3.7.7. Retorno Sucesso

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

Http status: 200

4.3.7.7.1. Layout Retorno

CAMPO DESCRIÇÃO

impressao Lista documentos para impressão.

impressoCCe Lista de eventos de carta de correção para impressão.

id

nota

Consultar arquivo de exemplo: cte_response_getImpressao.txt

4.3.7.8. Retorno Erro

Não há

5. MÓDULO MDFE

5.1. OBSERVAÇÕES GERAIS

Resumindo o processo, primeiramente é enviado um pacote de dados; depois é feita uma consulta

recebendo uma lista de ids e, então por fim, marcam-se no sistema os ids consultados para que numa

próxima consulta eles não sejam retornados novamente, também são retornados os MDF-es para

impressão via printer.

Para todos os requests é preciso usar basic authentication utilizando o usuário e a senha fornecidos.

Com isso basta realizar POST para enviar os pacotes e GET para consultar o resultado do

processamento. O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag

"txt_conteudo".

O separador de campos do conteúdo é o pipe ( | ). Para quebra de linha usa-se \n.

76

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Para enviar vários MDF-es você deve concatenar as strings antes de colocar em txt_conteúdo.Txt

conteúdo terá vários "{"config": " .. ", "xml" : "..."} separando-os por vírgula. No caso de cancelamento e

encerramento o procedimento é o mesmo.

5.2. MÉTODO: POST

5.2.1. EnviarPacote:

5.2.1.1. Introdução

Método para envio de MDF-es para serem autorizadas pela Sefaz correspondente.

5.2.1.2. URL:

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

5.2.1.3. Exemplo URL:

http://localhost:8080/webservice/api/mdfe (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/mdfe (ambiente de homologação do SaaS)

5.2.1.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG.

action Ação solicitada Sim

referencia Nome do arquivo utilizado na integração. Não

txt_conteudo Grupo de informações do MDF-e Sim

xml Conteúdo do XML de MDF-e. Informar dados

conforme layout padrão da Receita Federal. Sim

config Configurações. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

5.2.1.5. Permissões

Permissões conforme cadastro de usuários:

77

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

5.2.1.6. Cabeçalho

Detalhes que devem ser informados na requisição:

- o usuário e

a senha fornecidos.

- -

5.2.1.7. Envio

O corpo do POST (request body) deve ser um json contendo todos os campos do layout do método.

Exemplo de Request Body conforme arquivo de exemplo: mdfe_request_post_enviar_pacote.txt

5.2.1.8. Retorno Sucesso

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

Http status: 202

5.2.1.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 400, 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

5.2.2. Cancelar

5.2.2.1. Introdução

Método para cancelar MDF-es enviados ao webservice.

5.2.2.2. URL:

78

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

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

5.2.2.3. Exemplo URL:

http://localhost:8080/webservice/api/mdfe (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/mdfe (ambiente de homologação do SaaS)

5.2.2.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG

action Ação solicitada Sim

referencia Nome do arquivo de integração Não

txt_conteudo Grupo de informações de cancelamento. Sim

xml

Conteúdo do Cancelamento de MDF-e. Informar dados

conforme layout padrão da Receita Federal mais a tag <IE>

para ser utilizada em processos internos.

Sim

config Configurações. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

5.2.2.5. Permissões

Permissões conforme cadastro de usuários:

- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

5.2.2.6. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- -

79

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

5.2.2.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "txt_conteudo".

Exemplo de Request Body conforme arquivo de exemplo: mdfe_request_post_cancelar.txt

5.2.2.8. Retorno Sucesso

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

Http status: 200 (Solicitação enviada com sucesso)

5.2.2.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 400, 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

5.2.3. Encerrar

5.2.3.1. Introdução

Método para encerrar MDF-es.

5.2.3.2. URL:

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

5.2.3.3. Exemplo URL:

http://localhost:8080/webservice/api/mdfe (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/mdfe (ambiente de homologação do SaaS)

5.2.3.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG.

action Ação solicitada Encerrar Sim

80

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

referencia Nome do arquivo de integração Não

txt_conteudo Grupo de informações de inutilização. Sim

xml

Conteúdo da Inutilização de MDF-e. Informar dados

conforme layout padrão da Receita Federal mais a tag <IE>

para ser utilizada em processos internos.

Sim

config Configurações. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

5.2.3.5. Permissões

Permissões conforme cadastro de usuários:

- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

5.2.3.6. Cabeçalho

Detalhes que devem ser informados na requisição:

- authentication utilizando o usuário e

a senha fornecidos.

- -

5.2.3.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "txt_conteudo".

Exemplo de Request Body conforme arquivo de exemplo: mdfe_request_post_encerrar.txt

5.2.3.8. Retorno Sucesso

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

Http status: 200 (Solicitação enviada com sucesso)

5.2.3.9. Retorno Erro

81

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Response Body: {"result":"<descrição do erro>"}

Http status: 400, 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

5.2.4. MarcarConsultado

5.2.4.1. Introdução

Método para indicar ao WebService que determinados documentos já foram consultados e não precisam

mais ser retornados na consulta (GET).

Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de

retorno.

5.2.4.2. URL:

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

5.2.4.3. Exemplo URL:

http://localhost:8080/webservice/api/mdfe (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/mdfe (ambiente de homologação do SaaS)

5.2.4.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG.

action Ação solicitada Sim

ids Listagem de ids dos processamentos a

serem marcados como consultados. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

5.2.4.5. Permissões

Permissões conforme cadastro de usuários:

- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

82

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

5.2.4.6. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- -

5.2.4.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids".

Exemplo de Request Body conforme arquivo de exemplo: mdfe_request_post_marcar_consultado.txt

5.2.4.8. Retorno Sucesso

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

Http status: 200 (Solicitação enviada com sucesso)

5.2.4.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

5.2.5. MarcarImpresso

5.2.5.1. Introdução

Método para indicar ao WebService que determinados documentos já foram impressos e não precisam

mais ser retornados na consulta (GET).

Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de

retorno.

83

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

5.2.5.2. URL:

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

5.2.5.3. Exemplo URL:

http://localhost:8080/webservice/api/mdfe (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/mdfe (ambiente de homologação do SaaS)

5.2.5.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG

action Ação solicitada Sim

ids Grupo de informações para marcar como impresso. Sim

idProcessamento Id do processamento a ser marcado. Sim

idNota Id da nota a ser marcada. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

5.2.5.5. Permissões

Permissões conforme cadastro de usuários:

- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

5.2.5.6. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- -

5.2.5.7. Envio

84

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids".

Exemplo de Request Body conforme arquivo de exemplo: mdfe_request_post_marcar_impresso.txt

5.2.5.8. Retorno Sucesso

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

Http status: 200 (Solicitação enviada com sucesso)

5.2.5.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

5.3. MÉTODO: GET

5.3.1. Consulta Padrão

5.3.1.1. Introdução

Método para obter os retornos dos documentos enviados, lista de documentos não consultados, dados

de lotes inutilizados e os documentos que devem ser enviados para o Printer imprimir.

5.3.1.2. URL:

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

5.3.1.3. Exemplo URL:

http://localhost:8080/webservice/api/mdfe (instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/mdfe (ambiente de homologação do SaaS)

5.3.1.4. Permissões

Permissões conforme cadastro de usuários:

85

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

5.3.1.5. Cabeçalho

Detalhes que devem ser informados na requisição:

- é preciso usar basic authentication utilizando o usuário e

a senha fornecidos.

5.3.1.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

5.3.1.7. Retorno Sucesso

Response Body: {"impressao":[],"retorno":{"mdfeCtes":[],"ids":[]}}

Http status: 200

5.3.1.7.1. Layout Retorno

CAMPO DESCRIÇÃO

impressao Lista documentos para impressão.

id

nota

retorno Grupo de informações para geração dos arquivos de retorno.

ids consultados.

mdfeCtes MDF-es que foram processadas pelo

software.

Consultar arquivo de exemplo: mdfe_response_get.txt

5.3.1.8. Retorno Erro

86

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Não há

5.3.2. GetXml

5.3.2.1. Introdução

Método para obter o XML de envio da respectiva chave de MDF-e.

5.3.2.2. URL:

<host>:<port>/<webservice>/api/mdfe/<chave cte>/getXml

5.3.2.3. Exemplo URL:

http://localhost:8080/webservice/api/mdfe/<chave cte>/getXml

(instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/mdfe/<chave cte>/getXml

(ambiente de homologação do SaaS)

5.3.2.4. Permissões

Permissões conforme cadastro de usuários:

- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

5.3.2.5. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- - -8859- Para o xml retornar com a codificação

correta.

87

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

5.3.2.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

5.3.2.7. Retorno Sucesso

Response Body: XML processado.

Http status: 200

Consultar arquivo de exemplo: mdfe_response_get_xml.txt

5.3.2.8. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 203, 404, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

5.3.3. Consulta Retorno

5.3.3.1. Introdução

Método para obter os retornos dos documentos enviados, lista de documentos não consultados e dados

de lotes inutilizados.

5.3.3.2. URL:

<host>:<port>/<webservice>/api/mdfe/getRetorno

5.3.3.3. Definir quantidade de Results da consulta:

<host>:<port>/<webservice>/api/mdfe/getRetorno?maxResults=

Quando não informada quantidade no parâmetro, será considerada a quantidade de 50 (cinquenta)

results para cada consulta.

5.3.3.4. Filtro de Série

88

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Para filtrar a consulta pela série, a mesma deverá ser enviada na URL. Se houver mais de uma, separá-

las por vírgula.

5.3.3.5. Exemplo URL com filtro:

http://localhost:8085/webservice/api/mdfe/getRetorno/serie=700

Ou

http://localhost:8085/webservice/api/mdfe/getRetorno/serie=700,701,703

http://localhost:8085/webservice/api/mdfe/getRetorno/serie=700?maxResults=100

Ou

http://localhost:8085/webservice/api/mdfe/getRetorno/serie=700,701,703?maxResults=100

5.3.3.6. Exemplo URL sem filtro:

http://localhost:8080/webservice/api/mdfe/getRetorno (instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/mdfe/getRetorno (ambiente de homologação do SaaS)

5.3.3.7. Permissões

Permissões conforme cadastro de usuários:

- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

5.3.3.8. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

5.3.3.9. Envio

Nenhum dado além do cabeçalho deverá ser informado.

89

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

5.3.3.10. Retorno Sucesso

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

Http status: 200

5.3.3.10.1. Layout Retorno

CAMPO DESCRIÇÃO

retorno Grupo de informações para geração dos arquivos de retorno.

ids consultados.

mdfeCtes -es que foram processadas pelo

software.

Consultar arquivo de exemplo: mdfe_response_getRetorno.txt

5.3.3.11. Retorno Erro

Não há

5.3.4. Consulta Impressão

5.3.4.1. Introdução

Método para obter os retornos dos documentos que devem ser enviados para o Printer imprimir.

5.3.4.2. URL:

<host>:<port>/<webservice>/api/mdfe/getImpressao

5.3.4.3. Exemplo URL:

http://localhost:8080/webservice/api/mdfe/getImpressao (instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/mdfe/getImpressao (ambiente de homologação do SaaS)

90

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

5.3.4.4. Permissões

Permissões conforme cadastro de usuários:

- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

5.3.4.5. Cabeçalho

Detalhes que devem ser informados na requisição:

- é preciso usar basic authentication utilizando o usuário e

a senha fornecidos.

5.3.4.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

5.3.4.7. Retorno Sucesso

Response Body: {"impressao":[]}

Http status: 200

5.3.4.7.1. Layout Retorno

CAMPO DESCRIÇÃO

impressao Lista documentos para impressão.

id

nota

Consultar arquivo de exemplo: mdfe_response_getImpressao.txt

5.3.4.8. Retorno Erro

Não há

91

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

5.3.5. GetDamdfe

5.3.5.1. Introdução

Método para obter o DAMDFE da respectiva chave de MDF-e.

5.3.5.2. URL:

<host>:<port>/<webservice>/api/mdfe/<chave mdfe>/getDamdfe

5.3.5.3. Exemplo URL:

http://localhost:8080/webservice/api/mdfe/<chave mdfe>/getDamdfe

(instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/mdfe/<chave mdfe>/getDamdfe

(ambiente de homologação do SaaS)

5.3.5.4. Permissões

Permissões conforme cadastro de usuários:

- MDF-e Integrador (ROLE_MDFE_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

5.3.5.5. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

5.3.5.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

92

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

5.3.5.7. Retorno Sucesso

Response Body: retornará um array de bytes (byte[]). Esse retorno terá de ser escrito em disco com

Http status: 200

5.3.5.8. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 203, 404, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

6. MÓDULO RECEPTOR NFSE (SERVIÇO)

6.1. OBSERVAÇÕES GERAIS

Existem poucos métodos para esse módulo, existe somente um método POST (MarcarConsultado) e um

método GET (Consulta Padrão).

Resumindo o processo, é feita uma consulta recebendo uma lista de ids e, então por fim, marcam-se no

sistema os ids consultados para que, numa próxima consulta, eles não sejam retornados novamente.

6.2. Método: POST

6.2.1. MarcarConsultado:

6.2.1.1. Introdução

Método para indicar ao WebService que determinados documentos já foram consultados e não precisam

mais ser retornados na consulta (GET).

Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de

retorno.

6.2.1.2. URL:

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

93

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

6.2.1.3. Exemplo URL:

http://localhost:8080/webservice/api/receptor_nfs (instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/receptor_nfs (ambiente de homologação do SaaS)

6.2.1.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG.

action Ação solicitada Sim

ids Listagem de ids dos processamentos a serem marcados

como consultados. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

6.2.1.5. Permissões

Permissões conforme cadastro de usuários:

- Administrar o sistema (ROLE_SUPER_ADMIN)

6.2.1.6. Cabeçalho

Detalhes que devem ser informados na requisição:

- usar basic authentication utilizando o usuário e

a senha fornecidos.

- -

6.2.1.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids" com uma

lista de ids dos documentos a serem marcados.

Exemplo de Request Body conforme arquivo de exemplo:

receptor_nfs_request_post_marcar_consultado.txt

94

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

6.2.1.8. Retorno Sucesso

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

Http status: 200 (Solicitação enviada com sucesso)

6.2.1.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

6.3. MÉTODO: GET

6.3.1. Consulta Padrão

6.3.1.1. Introdução

Método para obter os retornos dos documentos recebidos e uma lista de documentos não consultados.

6.3.1.2. URL:

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

6.3.1.3. Exemplo URL:

http://localhost:8080/webservice/api/receptor_nfs (instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/receptor_nfs (ambiente de homologação do SaaS)

6.3.1.4. Permissões

Permissões conforme cadastro de usuários:

- Administrar o sistema (ROLE_SUPER_ADMIN)

6.3.1.5. Cabeçalho

95

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Detalhes que devem ser informados na requisição:

- usar basic authentication utilizando o usuário e

a senha fornecidos.

6.3.1.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

6.3.1.7. Retorno Sucesso

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

Http status: 200

Consultar arquivo de exemplo: receptor_nfse_response_get.txt

6.3.1.7.1. Layout Retorno

CAMPO DESCRIÇÃO

retorno Grupo de informações para geração dos arquivos de retorno.

ids consultados.

nfss -es que foram processadas pelo

software.

6.3.1.8. Retorno Erro

Não há

7. MÓDULO RECEPTOR NFE (MERCANTIL)

7.1. OBSERVAÇÕES GERAIS

Esse módulo necessita que sejam enviados os XMLs recebidos de fornecedores e depois que sejam

marcados como consultados.

Como em todos os módulos existe uma consulta padrão (GET) e também alguns métodos para consulta

de XMLs (processados e cancelados).

96

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

7.2. MÉTODO: POST

7.2.1. EnviarRecebimento

7.2.1.1. Introdução

Método para envio de NF-es de fornecedores ao WebService.

7.2.1.2. URL:

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

7.2.1.3. Exemplo URL:

http://localhost:8080/webservice/api/recebimentoNfe (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe (ambiente de homologação do SaaS)

7.2.1.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG.

action Ação solicitada Sim

referencia Nome do arquivo utilizado na integração. Não

txt_conteudo Conteúdo do XML de NF-e. Informar dados

conforme layout padrão da Receita Federal. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

7.2.1.5. Permissões

Permissões conforme cadastro de usuários:

- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

97

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

7.2.1.6. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- -

7.2.1.7. Envio

O corpo do POST (request body) deve ser um json contendo todos os campos do layout do método.

Exemplo de Request Body conforme arquivo de exemplo:

receptor_nfe_request_post_enviar_recebimento.txt

7.2.1.8. Retorno Sucesso

Response Body: {"resul

Http status: 202

7.2.1.8.1. Layout Retorno

CAMPO DESCRIÇÃO

result

anoMes Ano e mês da emissão.

cnpjEmitente CNPJ do Emitente.

recebimento Tipo

cnpjDestinatario CNPJ do Destinatário.

Consultar arquivo de exemplo: receptor_nfe_response_post_enviar_recebimento.txt

7.2.1.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 400, 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

98

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

7.2.2. EnviarEventoManifestacao

7.2.2.1. Introdução

Método para envio de eventos de manifestação do destinatário.

7.2.2.2. URL:

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

7.2.2.3. Exemplo URL:

http://localhost:8080/webservice/api/recebimentoNfe (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe (ambiente de homologação do SaaS)

7.2.2.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG

action Ação solicitada EnviarEventoManifestacao Sim

referencia Nome do arquivo utilizado na integração. Não

txt_conteudo Conteúdo do XML de NF-e. Informar dados

conforme layout padrão da Receita Federal. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

7.2.2.5. Permissões

Permissões conforme cadastro de usuários:

- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

7.2.2.6. Cabeçalho

Detalhes que devem ser informados na requisição:

99

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

-

a senha fornecidos.

- -

7.2.2.7. Envio

O corpo do POST (request body) deve ser um json contendo todos os campos do layout do método.

Exemplo de Request Body conforme arquivo de exemplo:

receptor_nfe_request_post_enviar_evento_manifestacao.txt

7.2.2.8. Retorno Sucesso

Response Body: {"result":"OK","descricao":"Evento [CIENCIA_OPERACAO] solicitado com sucesso."}

Http status: 202

7.2.2.8.1. Layout Retorno

CAMPO DESCRIÇÃO

result

descricao Descrição do resultado do envio.

Consultar arquivo de exemplo:

receptor_nfe_response_post_enviar_evento_manifestacao_ok.txt

7.2.2.9. Retorno Erro

Response Body: {"result": "erro","descricao": "Não foi encontrada nota recebida com chave de acesso:

12345 para a empresa com CNPJ: 000 e Inscrição Estadual: 000" }

Http status: 400, 412, 500.

Consultar arquivos de exemplo para erros:

receptor_nfe_response_post_enviar_evento_manifestacao_erro.txt

receptor_nfe_response_post_enviar_evento_manifestacao_erro_2.txt

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

100

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

7.2.3. MarcarConsultado:

7.2.3.1. Introdução

Método para indicar ao WebService que determinados documentos já foram consultados e não precisam

mais ser retornados na consulta (GET).

Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de

retorno.

7.2.3.2. URL:

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

7.2.3.3. Exemplo URL:

http://localhost:8080/webservice/api/recebimentoNfe (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe (ambiente de homologação do SaaS)

7.2.3.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG.

action Ação solicitada Sim

ids Listagem de ids dos processamentos a serem

marcados como consultados. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

7.2.3.5. Permissões

Permissões conforme cadastro de usuários:

- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

7.2.3.6. Cabeçalho

Detalhes que devem ser informados na requisição:

101

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

-

a senha fornecidos.

- -

7.2.3.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids" com uma

lista de ids dos documentos a serem marcados.

Exemplo de Request Body conforme arquivo de exemplo:

receptor_nfe_request_post_marcar_consultado.txt

7.2.3.8. Retorno Sucesso

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

Http status: 200 (Solicitação enviada com sucesso)

7.2.3.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

7.2.4. MarcarImpresso:

7.2.4.1. Introdução

Método para indicar ao WebService que determinados documentos já foram impressos e não precisam

mais ser retornados na consulta (GET).

Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de

retorno.

7.2.4.2. URL:

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

102

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

7.2.4.3. Exemplo URL:

http://localhost:8080/webservice/api/recebimentoNfe (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe (ambiente de homologação do SaaS)

7.2.4.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG

action Ação solicitada Sim

ids Grupo de informações para marcar como impresso. Sim

idProcessamento Id do processamento a ser marcado. Sim

idNota Id da nota a ser marcada. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

7.2.4.5. Permissões

Permissões conforme cadastro de usuários:

- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

7.2.4.6. Cabeçalho

Detalhes que devem ser informados na requisição:

- authentication utilizando o usuário e

a senha fornecidos.

- -

7.2.4.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag "action" e uma tag "ids".

Exemplo de Request Body conforme arquivo de exemplo:

receptor_nfe_request_post_marcar_impresso.txt

103

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

7.2.4.8. Retorno Sucesso

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

Http status: 200 (Solicitação enviada com sucesso)

7.2.4.9. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

7.3. MÉTODO: GET

7.3.1. Consulta Padrão

7.3.1.1. Introdução

Método para obter os retornos dos documentos enviados e a lista de documentos não consultados.

7.3.1.2. URL:

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

7.3.1.3. Exemplo URL:

http://localhost:8080/webservice/api/recebimentoNfe (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe (ambiente de homologação do SaaS)

7.3.1.4. Permissões

Permissões conforme cadastro de usuários:

- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

104

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

7.3.1.5. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

7.3.1.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

7.3.1.7. Retorno Sucesso

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

Http status: 200

7.3.1.7.1. Layout Retorno

CAMPO DESCRIÇÃO

Retorno Grupo de informações para geração dos arquivos de retorno.

Ids consultados.

Recebimentos NF-es que foram processadas pelo

software.

Consultar arquivo de exemplo: receptor_nfe_response_get.txt

7.3.1.8. Retorno Erro

Não há

7.3.2. GetXml

7.3.2.1. Introdução

Método para obter o XML processado da respectiva chave de NF-e.

105

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

7.3.2.2. URL:

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

7.3.2.3. Exemplo URL:

http://localhost:8080/webservice/api/recebimentoNfe/<chave nfe>/getXml

(instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe/<chave nfe>/getXml

(ambiente de homologação do SaaS)

7.3.2.4. Permissões

Permissões conforme cadastro de usuários:

- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

7.3.2.5. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- - -8859- Para o xml retornar com a codificação

correta.

7.3.2.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

7.3.2.7. Retorno Sucesso

Response Body: XML processado.

106

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Http status: 200

Consultar arquivo de exemplo: receptor_nfe_response_get_xml.txt

7.3.2.8. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 203, 404, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

7.3.3. GetXmlCancelamento

7.3.3.1. Introdução

Método para obter o XML cancelado da respectiva chave de NFe.

7.3.3.2. URL:

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

7.3.3.3. Exemplo URL:

http://localhost:8080/webservice/api/recebimentoNfe/<chave nfe>/getXmlCancelamento

(instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe/<chave nfe>/getXmlCancelamento

(ambiente de homologação do SaaS)

7.3.3.4. Permissões

Permissões conforme cadastro de usuários:

- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

107

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

7.3.3.5. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- - -8859- Para o xml retornar com a codificação

correta.

7.3.3.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

7.3.3.7. Retorno Sucesso

Response Body: XML de cancelamento processado.

Http status: 200

Consultar arquivo de exemplo: receptor_nfe_response_get_xml_cancelado.txt

7.3.3.8. Retorno Erro

Response Body: {"result":"<descrição do erro>"}

Http status: 203, 404, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

7.3.4. GetStatus

7.3.4.1. Introdução

Método para obter o Status (Código-Descrição) da respectiva chave de NF-e.

7.3.4.2. URL:

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

108

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

7.3.4.3. Exemplo URL:

http://localhost:8080/webservice/api/recebimentoNfe/<chave nfe>/getStatus

(instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe/<chave nfe>/getStatus

(ambiente de homologação do SaaS)

7.3.4.4. Permissões

Permissões conforme cadastro de usuários:

- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

7.3.4.5. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

7.3.4.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

7.3.4.7. Retorno Sucesso

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

Http status: 200

7.3.4.8. Layout Retorno

CAMPO DESCRIÇÃO

Retorno Grupo de informações para geração dos arquivos de retorno.

Ids Não há.

109

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Recebimentos -es que foram solicitados.

7.3.4.9. Retorno Erro

Não há

7.3.5. Consulta Impressão

7.3.5.1. Introdução

Método para obter os retornos dos documentos que devem ser enviados para o Printer imprimir.

7.3.5.2. URL:

<host>:<port>/<webservice>/api/recebimentoNfe/getImpressao

7.3.5.3. Exemplo URL:

http://localhost:8080/webservice/api/recebimentoNfe/getImpressao (instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/recebimentoNfe/getImpressao (ambiente de homologação do

SaaS)

7.3.5.4. Permissões

Permissões conforme cadastro de usuários:

- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

7.3.5.5. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

110

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

7.3.5.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

7.3.5.7. Retorno Sucesso

Response Body: {"impressao":[]}

Http status: 200

7.3.5.7.1. Layout Retorno

CAMPO DESCRIÇÃO

impressao Lista documentos para impressão.

idProcessamento

params

Consultar arquivo de exemplo: receptor_nfe_response_getImpressao.txt

7.3.5.8. Retorno Erro

Não há

8. MÓDULO RECEPTOR CTE

8.1. OBSERVAÇÕES GERAIS

Esse módulo necessita que sejam enviados os XMLs recebidos e depois que sejam marcados como

consultados. É possível ainda consultar um documento e obter o seu XML.

Como em todos os módulos existe uma consulta padrão (GET) e também alguns métodos para consulta

de XMLs (processados e cancelados).

8.2. MÉTODO: POST

8.2.1. EnviarRecebimento

111

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

8.2.1.1. Introdução

Método para envio de NF-es de fornecedores ao WebService.

8.2.1.2. URL:

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

8.2.1.3. Exemplo URL:

http://localhost:8080/webservice/api/recebimento (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/recebimento (ambiente de homologação do SaaS)

8.2.1.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG

action Ação solicitada Sim

referencia Nome do arquivo utilizado na integração. Não

txt_conteudo Conteúdo do XML de CT-e. Informar dados

conforme layout padrão da Receita Federal. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

8.2.1.5. Permissões

Permissões conforme cadastro de usuários:

- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

- Receptor CT-e Consultar Chave via Webservice (ROLE_RECEBIMENTO_CONSULTACHAVE_CTE)

- Receptor CT-e Resgatar XML via Webservice (ROLE_RECEBIMENTO_RESGATAXML_CTE)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

8.2.1.6. Cabeçalho

Detalhes que devem ser informados na requisição:

112

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

-

a senha fornecidos.

- -

8.2.1.7. Envio

O corpo do POST (request body) deve ser um json contendo todos os campos do layout do método.

Exemplo de Request Body conforme arquivo de exemplo:

receptor_cte_request_post_enviar_recebimento.txt

8.2.1.8. Retorno Sucesso

Response Body: { result : OK , anoMes : , cnpjEmitente : , recebimento : : }

Http status: 202

8.2.1.8.1. Layout Retorno

CAMPO DESCRIÇÃO

result

anoMes Ano e mês da emissão.

cnpjEmitente CNPJ do Emitente.

Recebimento

cnpjDestinatario CNPJ do Destinatário.

Consultar arquivo de exemplo: receptor_cte_response_post_enviar_recebimento.txt

8.2.1.9. Retorno Erro

Response Body: { result : <descrição do erro> }

Http status: 400, 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

8.2.2. ConsultarDocFornecedor

8.2.2.1. Introdução

113

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Método para consultar status de CT-e recebido. A consulta pode ser feita usando a chave do documento

ou através da combinação de CNPJ, IE, número e série.

8.2.2.2. URL:

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

8.2.2.3. Exemplo URL:

http://localhost:8080/webservice/api/recebimento (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/recebimento (ambiente de homologação do SaaS)

8.2.2.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG

action Ação solicitada ConsultarDocFornecedor Sim

txt_conteudo Grupo de informações para consulta. Sim

tpDoc para consulta.

- Sim

chave

-e.

Informar quando não for informar os outros

Não

cnpj

informado.

Não

ie

Não

nrDoc

Número do CT-e.

informado.

Não

serie -e. Não

Não

*Outras tags informadas não serão utilizadas, portanto, não as informe.

8.2.2.5. Permissões

114

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Permissões conforme cadastro de usuários:

- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

- Receptor CT-e Consultar Chave via Webservice (ROLE_RECEBIMENTO_CONSULTACHAVE_CTE)

- Receptor CT-e Resgatar XML via Webservice (ROLE_RECEBIMENTO_RESGATAXML_CTE)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

8.2.2.6. Cabeçalho

Detalhes que devem ser informados na requisição:

- preciso usar basic authentication utilizando o usuário e

a senha fornecidos.

- -

8.2.2.7. Envio

O corpo do POST (request body) deve ser um json contendo todos os campos do layout do método.

Exemplo de Request Body conforme arquivo de exemplo (Consulta pela Chave):

receptor_cte_request_post_consultar_doc_fornecedor_1.txt

Exemplo de Request Body conforme arquivo de exemplo (Consulta pelos dados do CT-e):

receptor_cte_request_post_consultar_doc_fornecedor_2.txt

8.2.2.8. Retorno Sucesso

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

Http status: 202

8.2.2.8.1. Layout Retorno

CAMPO DESCRIÇÃO

result

status Código do status do documento.

115

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

8.2.2.9. Retorno Erro

Response Body: { result : <descrição do erro> }

Http status: 400, 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

8.2.3. ResgatarXmlFornecedor

8.2.3.1. Introdução

Método para resgatar XML de CT-e recebido. A consulta pode ser feita usando a chave do documento ou

através da combinação de CNPJ, IE, número e série.

8.2.3.2. URL:

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

8.2.3.3. Exemplo URL:

http://localhost:8080/webservice/api/recebimento (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/recebimento (ambiente de homologação do SaaS)

8.2.3.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG

action Ação solicitada ResgatarXmlFornecedor Sim

txt_conteudo Grupo de informações para consulta. Sim

tpDoc Atributo

para consulta. - Sim

chave

-e.

Informar quando não for informar os outros

Não

cnpj Não

informado.

Não

116

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

ie

Não

nrDoc -e. Não

Não

serie -e. Não

Não

*Outras tags informadas não serão utilizadas, portanto, não as informe.

8.2.3.5. Permissões

Permissões conforme cadastro de usuários:

- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

- Receptor CT-e Consultar Chave via Webservice (ROLE_RECEBIMENTO_CONSULTACHAVE_CTE)

- Receptor CT-e Resgatar XML via Webservice (ROLE_RECEBIMENTO_RESGATAXML_CTE)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

8.2.3.6. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- ent-

8.2.3.7. Envio

O corpo do POST (request body) deve ser um json contendo todos os campos do layout do método.

Exemplo de Request Body conforme arquivo de exemplo (Consulta pela Chave):

receptor_cte_request_post_resgatar_xml_fornecedor_1.txt

Exemplo de Request Body conforme arquivo de exemplo (Consulta pelos dados do CT-e):

receptor_cte_request_post_resgatar_xml_fornecedor_2.txt

117

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

8.2.3.8. Retorno Sucesso

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

Http status: 202

8.2.3.8.1. Layout Retorno

CAMPO DESCRIÇÃO

result

xml Conteúdo do XML.

Consultar arquivo de exemplo: receptor_cte_response_post_resgatar_xml_fornecedor.txt

8.2.3.9. Retorno Erro

Response Body: { result : <descrição do erro> }

Http status: 400, 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

8.2.4. MarcarConsultado:

8.2.4.1. Introdução

Método para indicar ao WebService que determinados documentos já foram consultados e não precisam

mais ser retornados na consulta (GET).

Deve ser utilizado depois do método de consulta onde são listados os documentos para geração de

retorno.

8.2.4.2. URL:

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

8.2.4.3. Exemplo URL:

http://localhost:8080/webservice/api/recebimento (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/recebimento (ambiente de homologação do SaaS)

118

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

8.2.4.4. Layout

CAMPO DESCRIÇÃO CONTEÚDO OBRIG

action Ação solicitada Sim

ids Listagem de ids dos processamentos a serem marcados

como consultados. Sim

*Outras tags informadas não serão utilizadas, portanto, não as informe.

8.2.4.5. Permissões

Permissões conforme cadastro de usuários:

- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

- Receptor CT-e Consultar Chave via Webservice (ROLE_RECEBIMENTO_CONSULTACHAVE_CTE)

- Receptor CT-e Resgatar XML via Webservice (ROLE_RECEBIMENTO_RESGATAXML_CTE)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

8.2.4.6. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- -

8.2.4.7. Envio

O corpo do POST (request body) deve ser um json contendo uma tag action e uma tag ids com uma

lista de ids dos documentos a serem marcados.

Exemplo de Request Body conforme arquivo de exemplo:

receptor_cte_request_post_marcar_consultado.txt

8.2.4.8. Retorno Sucesso

119

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Response Body: { result : OK }

Http status: 200 (Solicitação enviada com sucesso)

8.2.4.9. Retorno Erro

Response Body: { result : <descrição do erro> }

Http status: 412, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

8.3. MÉTODO: GET

8.3.1. Consulta Padrão

8.3.1.1. Introdução

Método para obter os retornos dos documentos enviados e a lista de documentos não consultados.

8.3.1.2. URL:

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

8.3.1.3. Exemplo URL:

http://localhost:8080/webservice/api/recebimento (instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/recebimento (ambiente de homologação do SaaS)

8.3.1.4. Permissões

Permissões conforme cadastro de usuários:

- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

- Receptor CT-e Consultar Chave via Webservice (ROLE_RECEBIMENTO_CONSULTACHAVE_CTE)

- Receptor CT-e Resgatar XML via Webservice (ROLE_RECEBIMENTO_RESGATAXML_CTE)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

120

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

8.3.1.5. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

8.3.1.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

8.3.1.7. Retorno Sucesso

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

Http status: 200

8.3.1.7.1. Layout Retorno

CAMPO DESCRIÇÃO

Retorno Grupo de informações para geração dos arquivos de retorno.

Ids ds dos processamentos que constam como não

consultados.

Recebimentos s CT-es que foram processadas pelo

software.

Consultar arquivo de exemplo: receptor_cte_response_get.txt

8.3.1.8. Retorno Erro

Não há

8.3.2. GetXml

8.3.2.1. Introdução

Método para obter o XML processado da respectiva chave de CT-e.

121

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

8.3.2.2. URL:

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

8.3.2.3. Exemplo URL:

http://localhost:8080/webservice/api/recebimento/<chave cte>/getXml

(instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/recebimento/<chave cte>/getXml

(ambiente de homologação do SaaS)

8.3.2.4. Permissões

Permissões conforme cadastro de usuários:

- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

- Receptor CT-e Consultar Chave via Webservice (ROLE_RECEBIMENTO_CONSULTACHAVE_CTE)

- Receptor CT-e Resgatar XML via Webservice (ROLE_RECEBIMENTO_RESGATAXML_CTE)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

8.3.2.5. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- - -8859- Para o xml retornar com a codificação

correta.

8.3.2.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

8.3.2.7. Retorno Sucesso

122

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Response Body: XML processado.

Http status: 200

Consultar arquivo de exemplo: receptor_cte_response_get_xml.txt

8.3.2.8. Retorno Erro

Response Body: { result : <descrição do erro> }

Http status: 203, 404, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

8.3.3. GetXmlCancelamento

8.3.3.1. Introdução

Método para obter o XML cancelado da respectiva chave de CT-e.

8.3.3.2. URL:

<host>:<port>/<webservice>/api/recebimento/<chave cte>/getXmlCancelamento

8.3.3.3. Exemplo URL:

http://localhost:8080/webservice/api/recebimento/<chave cte>/getXmlCancelamento

(instalação in house)

ou

https://ws.h.dfe.mastersaf.com.br/api/recebimento/<chave cte>/getXmlCancelamento

(ambiente de homologação do SaaS)

8.3.3.4. Permissões

Permissões conforme cadastro de usuários:

- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

- Receptor CT-e Consultar Chave via Webservice (ROLE_RECEBIMENTO_CONSULTACHAVE_CTE)

- Receptor CT-e Resgatar XML via Webservice (ROLE_RECEBIMENTO_RESGATAXML_CTE)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

123

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

8.3.3.5. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

- - -8859- Para o xml retornar com a codificação

correta.

8.3.3.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

8.3.3.7. Retorno Sucesso

Response Body: XML de cancelamento processado.

Http status: 200

Consultar arquivo de exemplo: receptor_cte_response_get_xml_cancelado.txt

8.3.3.8. Retorno Erro

Response Body: { result : <descrição do erro> }

Http status: 203, 404, 500.

*Consultar título LISTAGEM DE ERROS para maiores informações sobre os erros.

8.3.4. GetStatus

8.3.4.1. Introdução

Método para obter o Status (Código-Descrição) da respectiva chave de CT-e.

8.3.4.2. URL:

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

124

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

8.3.4.3. Exemplo URL:

http://localhost:8080/webservice/api/recebimento/<chave nfe>/getStatus

(instalação in house)

Ou

https://ws.h.dfe.mastersaf.com.br/api/recebimento/<chave nfe>/getStatus

(ambiente de homologação do SaaS)

8.3.4.4. Permissões

Permissões conforme cadastro de usuários:

- Receptor Integrador (ROLE_RECEBIMENTO_INTEGRADOR)

- Administrar o sistema (ROLE_SUPER_ADMIN)

* O usuário informado na requisição deve possuir ao menos uma destas permissões.

8.3.4.5. Cabeçalho

Detalhes que devem ser informados na requisição:

-

a senha fornecidos.

8.3.4.6. Envio

Nenhum dado além do cabeçalho deverá ser informado.

8.3.4.7. Retorno Sucesso

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

Http status: 200

8.3.4.8. Layout Retorno

CAMPO DESCRIÇÃO

Retorno Grupo de informações para geração dos arquivos de retorno.

Ids Não há.

125

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Recebimentos CT-es que foram solicitados.

8.3.4.9. Retorno Erro

Não há

9. LISTAGEM DE ERROS

- 203 Usuário e senha sem permissão de acessar o método/dados da empresa.

- 400 Erros ao de validação/parser/argumentos ilegais descritos no Response Body.

- 403 Forbidden Usuário e senha não foram informados corretamente.

- 404 Chave de acesso não encontrada.

- 412 JSON nao informado ou invalido ou nenhuma ação (campo action) encontrada.

- 415 Unsupported Media Type 125étodos125-type não foi informado corretamente.

- 500 Erro interno.

Mais informações sobre os códigos de retorno podem ser encontradas em:

http://en.wikipedia.org/wiki/List_of_http_status_codes

10. EXEMPLO DE COMO UTILIZAR O WEBSERVICE

10.1. OBSERVAÇÕES GERAIS

Utilize a extensão REST Client do Firefox para realizar os testes de comunicação.

http://restclient.net/

126

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

10.2. UTILIZANDO A EXTENSÃO REST CLIENT DO FIREFOX

10.2.1. Como informar os dados?

1º) Informar tipo de requisição

2º) Informar a URL:

3º) Informando usuário e senha:

127

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Informar o usuário e senha:

4º) Informando dados no cabeçalho (Content-type se necessário):

Selecionar menu

Informar dados de tipo de conteúdo, por exemplo:

128

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

5º) Informando conteúdo (corpo) da mensagem (se necessário):

10.2.2. Exemplo de POST

129

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

10.2.3. Exemplo de GET

11. PROGRAMA EXEMPLO EM JAVA

Junto deste Manual está disponível o código fonte de software capaz de testar os serviços oferecidos por

nosso WebService.

Depois de descompactá-lo siga os seguintes passos para utilizá-lo:

3) Importar este projeto no eclipse como um projeto maven. Para isto, acessar opção pelo menu File

-> Import -> Existing Maven Projects

2) Com o projeto importado, abrir a classe br.com.mastersaf.WSTest (Para testar método POST

enviarPacote da NF-e) ou br.com.mastersaf.WSPdfDacteTest (Teste para método GET getDacte do CT-e)

2.1) Configurar os atributos URL_WEBSERVICE, USER e PASSWORD

2.2) O usuário informado deverá ter a permissão de integrador no portal MASTERSAF.

130

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

2.3) Retornar no método getBodyRequest, o json da NFE com os seus dados. Este formato foi o mesmo

descrito neste manual.

12. RELAÇÃO DE MUDANÇAS DE VERSÕES DO MANUAL

Versão Data Mudanças Versão DF-e

1.00 22/08/2012 Criação do manual baseado em MASTERSAFDFE

Integração com Webservice.pdf -

1.01 25/09/2012 Incluído capítulo 5 MDF-E -

1.02 08/10/2012 Incluído item 3.3.4 GetDanfe -

1.03 29/11/2012

Incluído item 3.3.5 GetStatus

Incluído capítulo 12 Relação das Mudanças de Versões do

Manual

3.13.2

1.04 27/03/2013 Incluídos itens 3.3.6, 3.3.7, 4.3.5, 4.3.6, 5.3.3, 5.3.4 3.16.0

1.05 05/04/2013 Incluído exemplo de retorno do método GET para o módulo

Receptor NFS-e. 3.16.1

1.06 11/04/2013 Incluído item 7.2.2 referente a Eventos de Manifestação. 3.16.1

1.07 13/05/2013 Incluídos itens 3.3.6.3 e 3.3.6.4 referentes a Filtro do

método getRetorno. 3.17.0

1.08

26/06/2013

08/08/2013

Alterado nomes dos métodos getXmlCancelado para ficar

igual ao nome no produto (getXmlCancelamento).

Incluído item 4.3.5 GetStatus

3.19.1

1.09 16/08/2013

Incluída informação de charset na parte de cabeçalhos dos

métodos getXml e getXmlCancelamento para todos os

modulos

3.19.1

1.10 19/08/2013 Atualizado item 3.3.5.7 Retorno Sucesso

Adicionado item 3.3.5.8 Layout Retorno 3.19.2

1.11 20/09/2013

Adicionado item 2.3.1.3 Definir quantidade de Results da

consulta

Atualizado item 2.3.1.4 Exemplo URL

Adicionado item 3.3.1.3 Definir quantidade de Results da

consulta

Atualizado item 3.3.1.4 Exemplo URL

Atualizado item 3.3.1.8 Retorno Sucesso

Atualizado item 3.3.1.8.1 Layout Retorno

3.20.1

131

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

Adicionado item 3.3.6.3 Definir quantidade de Results da

consulta

Atualizado item 3.3.6.5 Exemplo URL com filtro

Atualizado item 3.3.6.6 Exemplo URL sem filtro

Adicionado item 4.3.1.3 Definir quantidade de Results da

consulta

Atualizado item 4.3.1.4 Exemplo URL

Adicionado item 4.3.6.3 Definir quantidade de Results da

consulta

Atualizado item 4.3.6.4 Exemplo URL

1.13 01/04/2014

Alteração deste manual para incluir um novo arquivo de

exemplo nfe_request_post_enviar_pacote_3.txt com todos

os 131étodos131f131 corretos referentes à 131étodos131f para

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

Alteração neste manual, no ponto 3.2.1.4 de post Nfe onde

diz: 131étodos131f Informações para contingência, pois

seguem mais informações, além das informações de

contingencia dentro do atributo 131étodos131f.

3.24.2

1.14 05/05/2014 Atualizado item 2.3.1.8.1 Layout Retorno

padronização do retorno. 3.25.2

1.15 22/07/2014 Incluído item: 4.2.3 EnviarCartaCorrecaoCte.

Atualizado 4.3.1 ConsultaPadrao módulo CT-e. 3.27.1

1.16 19/08/2014 Incluído item 2.2.6 Convertida, do módulo NFS-e. 3.28.0

1.17 02/09/2014

Incluido método getStatus para Recebimento NFE/CTE

Saas.

3.28.1

1.18 31/10/2014 Atualizado para alguns métodos do módulo nfe o novo

parâmetro na requisição id_integrador 3.30.0

1.19 25/11/2014 Atualizado a estrutura de retorno para 131étodos GET com

novo parâmetro contendo link de acesso direto ao DANFE. 3.30.1

1.20 29/12/2014 2.3.1 Consulta Padrão Atualizado parâmetros de filtro

disponíveis. 3.26.0

1.20 30/12/2014 3.2.7 MarcarCartaCorrecaoImpresso Incluindo método 3.13.0

1.20 30/12/2014 4.2.7 MarcarCartaCorrecaoImpresso Incluindo método 3.27.1

1.20 30/12/2014 4.3.6 Consulta Retorno Atualizado parâmetros de filtro

disponíveis. 3.25.3

132

MASTERSAF DFE INTEGRAÇÃO COM WEBSERVICE DF-E V3

Versão: 1.22 Atualizado em: 09/06/2015

1.20 30/12/2014 5.3.3 Consulta Retorno Atualizado parâmetros de filtro

disponíveis. 3.25.3

1.20 30/12/2014 5.3.5 GetDamdfe Incluindo método. 3.27.0

1.20 30/12/2014 7.2.4 MarcarImpresso Incluindo método 3.19.1

1.20 30/12/2014 7.3.5 Consulta Impressão Incluindo método 3.19.1

1.21 12/05/2015 Atualizando arquivos de exemplo de consulta de MDF-e.

Itens do manual: 5.3.1 e 5.3.3 3.34.1

1.21 12/05/2015

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

do manual:

3.3.1 - Consulta Padrão

3.3.7 - Consulta Retorno

3.34.1

1.21 12/05/2015

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

do manual:

4.3.1 - Consulta Padrão

4.3.7 - Consulta Retorno

3.34.1

13. SUPORTE TÉCNICO

Para dúvidas ou problemas, abra um chamado no Contact Center ou entre em contato com nossa equipe

de Suporte Técnico MASTERSAF pelo Telefone:

(11) 2159-0600 opção 02 (Atendimento das Soluções DFE).

Nosso horário de atendimento é de segunda à sexta-feira de 09h às 18h.