Webhooks

O Emites conta com um sistema de noticações por webhooks nas NFSes. Webhooks funcionam da seguinte forma: O usuário cadastra uma URL na área de gerenciamento de webhooks, o Emites então usa essa URL para fazer uma requisição do tipo POST a cada mudança de status de uma NFSe.

Caso a resposta seja da família 30x, 40x ou 50x, o Emites realizará mais três tentativas até conseguir uma resposta com status 200.

O corpo da requisição é o seguinte:

{
    "_links": {
        "rel": "self",
        "method": "GET",
        "url": "https://app.emites.com.br/api/v1/nfse/1"
    },
    "id": 1,
    "from_status": "processing",
    "to_status": "accepted"
}

Criação

Para cadastrar um novo webhook, você deve possuir uma URL que aceita requisições POST e GET, e responder sempre com o status HTTP 200. O Emites faz uma requisição teste para a URL informada afim de verificar a disponibilidade do serviço:

POST /api/v1/webhooks

Corpo de exemplo da requisição:

{
    "url": "https://seusistema.com.br/emites",
    "name": "Webhook teste"
}

Cabeçalho da resposta:

Status Code: 201
Location: https://sandbox.emites.com.br/api/v1/webhooks/1
Date: Tue, 04 Feb 2014 17:55:19 GMT
Vary: Accept, Cookie
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

Corpo da resposta:

{
    "_links": [
        {
            "href": "https://app.emites.com.br/api/v1/webhooks/1",
            "method": "GET",
            "rel": "self"
        }, {
            "href": "https://app.emites.com.br/api/v1/webhooks/1",
            "method": "PUT",
            "rel": "update"
        }, {
            "href": "https://app.emites.com.br/api/v1/webhooks/1",
            "method": "PATCH",
            "rel": "partial_update"
        }, {
            "href": "https://app.emites.com.br/api/v1/webhooks/1",
            "mehod": "DELETE",
            "rel": "destroy"
        }
    ],
    "id": 1,
    "name": "Webhook teste",
    "url": "http://seusistema.com.br/emites",
    "created_at": "2014-12-05T13:22:28.498Z"
}

O Emites também envia uma requisição teste para a URL informada, afim de testar se a mesma está dentro do padrão exigido, a requisição é a seguinte:

Cabeçalho da requisição:

Connection: close
Accept: */*
Content-Length: 14
User-Agent: emites-sandbox
Host: seusistema.com.br
Content-Type: application/json

Corpo da requisição:

{
    "test": true
}

Atualização

Você só pode atualizar o nome de um webhook. Caso queira alterar a URL do mesmo, remova-o e cadastre um novo objeto.

PUT /api/v1/webhooks/1

Corpo de exemplo da requisição:

{
    "name": "Outro teste"
}

Cabeçalho da resposta:

Status Code: 200
Location: https://sandbox.emites.com.br/api/v1/webhooks/1
Date: Tue, 04 Feb 2014 17:55:19 GMT
Vary: Accept, Cookie
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

Corpo da resposta:

{
    "_links": [
        {
            "href": "https://app.emites.com.br/api/v1/webhooks/1",
            "method": "GET",
            "rel": "self"
        }, {
            "href": "https://app.emites.com.br/api/v1/webhooks/1",
            "method": "PUT",
            "rel": "update"
        }, {
            "href": "https://app.emites.com.br/api/v1/webhooks/1",
            "method": "PATCH",
            "rel": "partial_update"
        }, {
            "href": "https://app.emites.com.br/api/v1/webhooks/1",
            "mehod": "DELETE",
            "rel": "destroy"
        }
    ],
    "id": 1,
    "name": "Outro teste",
    "url": "http://seusistema.com.br/emites",
    "created_at": "2014-12-05T13:22:28.498Z"
}

Listagem

GET /api/v1/webhooks

Cabeçalho da resposta:

Status Code: 200
Date: Tue, 04 Feb 2014 17:55:19 GMT
Vary: Accept, Cookie
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

Corpo da resposta:

{
    "count":1,
    "next":null,
    "previous":null,
    "collection":[
        {
            "_links":[
                {
                    "https://app.emites.com.br/api/v1/webhooks/1",
                    "method":"GET",
                    "rel":"self"
                }, {
                    "https://app.emites.com.br/api/v1/webhooks/1",
                    "method":"PUT",
                    "rel":"update"
                }, {
                    "https://app.emites.com.br/api/v1/webhooks/1",
                    "method":"PATCH",
                    "rel":"partial_update"
                }, {
                    "https://app.emites.com.br/api/v1/webhooks/1",
                    "method":"DELETE",
                    "rel":"destroy"
                }
            ],
            "id":1,
            "name":"Webhook teste",
            "url":"http://seusistema.com.br/emites",
            "created_at":"2015-03-12T17:27:57.350Z"
        }
    ]
}

Detalhes

GET /api/v1/webhooks/1

Cabeçalho da resposta:

Status Code: 200
Date: Tue, 04 Feb 2014 17:55:19 GMT
Vary: Accept, Cookie
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

Corpo da resposta:

{
    "_links":[
        {
            "https://app.emites.com.br/api/v1/webhooks/1",
            "method":"GET",
            "rel":"self"
        }, {
            "https://app.emites.com.br/api/v1/webhooks/1",
            "method":"PUT",
            "rel":"update"
        }, {
            "https://app.emites.com.br/api/v1/webhooks/1",
            "method":"PATCH",
            "rel":"partial_update"
        }, {
            "https://app.emites.com.br/api/v1/webhooks/1",
            "method":"DELETE",
            "rel":"destroy"
        }
    ],
    "id":1,
    "name":"Webhook teste",
    "url":"http://seusistema.com.br/emites",
    "created_at":"2015-03-12T17:27:57.350Z"
}

Remoção

Para remover um webhook, siga o exemplo abaixo:

DELETE /api/v1/webhooks/1

Cabeçalho da resposta:

Status Code: 204
Location: https://sandbox.emites.com.br/api/v1/webhooks/1
Date: Tue, 04 Feb 2014 17:55:19 GMT
Vary: Accept, Cookie
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

Na remoção, o corpo da requisição vem vazio.