Lotes

Lotes são um grupo de NFSe. Um lote possuí vários documentos que serão enviados ou cancelados de uma só vez. O lote só pode ser associado a uma NFSe somente se ele não tiver sido processado.

Criação

Criar um lote:

POST /api/v1/batches

Corpo de exemplo da requisição:

{
    "emitter_id": 1,
    "name": "lote maio de 2014"
}

Cabeçalho de exemplo da resposta:

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

Corpo de exemplo da resposta:

{
    "_links": [{
        "href": "https://app.emites.com.br/api/v1/batches/1",
        "method": "GET",
        "rel": "self"
    }, {
        "href": "https://app.emites.com.br/api/v1/batches/1/nfse",
        "method": "GET",
        "rel": "nfse"
    }, {
        "href": "https://app.emites.com.br/api/v1/batches/1/send",
        "method": "POST",
        "rel": "send"
    }, {
        "href": "https://app.emites.com.br/api/v1/batches/1/cancel",
        "method": "POST",
        "rel": "cancel"
    }, {
        "href": "https://app.emites.com.br/api/v1/batches/1/history",
        "method": "GET",
        "rel": "history"
    }, {
        "href": "https://app.emites.com.br/batches/show/1"
        "method": "GET"
        "rel": "html"
    }],
    "id": 1,
    "name": "batch-name",
    "emitter_id": 1,
    "status": "created",
    "properties": {
        "created": 0,
        "scheduled": 0,
        "processing": 0,
        "accepted": 0,
        "rejected": 0,
        "cancelled": 0,
        "cancelling": 0
        "total": 0
    }
}

Listagem

Para listar todos os lotes:

GET /api/v1/batches

Cabeçalho de exemplo 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 de exemplo da resposta:

{
    "count": 1,
    "next": null,
    "previous": null,
    "collection": [{
        "_links": [{
            "href": "https://app.emites.com.br/api/v1/batches/1",
            "method": "GET",
            "rel": "self"
        }, {
            "href": "https://app.emites.com.br/api/v1/batches/1/nfse",
            "method": "GET",
            "rel": "nfse"
        }, {
            "href": "https://app.emites.com.br/api/v1/batches/1/send",
            "method": "POST",
            "rel": "send"
        }, {
            "href": "https://app.emites.com.br/api/v1/batches/1/cancel",
            "method": "POST",
            "rel": "cancel"
        }, {
            "href": "https://app.emites.com.br/api/v1/batches/1/history",
            "method": "GET",
            "rel": "history"
        }, {
            "href": "https://app.emites.com.br/batches/show/1"
            "method": "GET"
            "rel": "html"
        }],
        "id": 1,
        "name": "batch-name",
        "emitter_id": 1,
        "status": "created",
        "properties": {
            "created": 0,
            "scheduled": 0,
            "processing": 0,
            "rejected": 0,
            "cancelled": 0,
            "cancelling": 0
            "total": 0
        }
    }]
}

Filtros

Para filtrar uma listagem de lotes:

GET /api/v1/batches?status=processed
Parâmetro Exemplo
status /api/v1/batches?status=created
emitter_id /api/v1/batches?emitter_id=1
name /api/v1/batches?name=batch+name

Cabeçalho de exemplo da resposta:

Status Code: 200
Date: Tue, 20 May 2014 12:43:23 GMT
Vary: Accept, Cookie
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
{
    "count": 1,
    "next": null,
    "previous": null,
    "collection": [{
        "_links": [{
            "href": "http://localhost:8000/api/v1/batches/1",
            "method": "GET",
            "rel": "self"
        }, {
            "href": "http://localhost:8000/api/v1/batches/1/nfse",
            "method": "GET",
            "rel": "nfse"
        }, {
            "href": "http://localhost:8000/api/v1/batches/1/send",
            "method": "POST",
            "rel": "send"
        }, {
            "href": "http://localhost:8000/api/v1/batches/1/cancel",
            "method": "POST",
            "rel": "cancel"
        }, {
            "href": "http://localhost:8000/api/v1/batches/1/history",
            "method": "GET",
            "rel": "history"
        }, {
            "href": "https://app.emites.com.br/batches/show/1"
            "method": "GET"
            "rel": "html"
        }],
        "id": 1,
        "name": "batch name",
        "emitter_id": 1,
        "status": "processed",
        "properties": {
            "scheduled": 0,
            "cancelling": 0,
            "accepted": 1,
            "processing": 0,
            "created": 0,
            "cancelled": 0,
            "total": 1,
            "rejected": 0
        }
    }]
}

Detalhes

Para os detalhes de um lote:

GET /api/v1/batches/1

Cabeçalho de exemplo 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
{
    "_links": [{
        "href": "https://app.emites.com.br/api/v1/batches/1",
        "method": "GET",
        "rel": "self"
    }, {
        "href": "https://app.emites.com.br/api/v1/batches/1/nfse",
        "method": "GET",
        "rel": "nfse"
    }, {
        "href": "https://app.emites.com.br/api/v1/batches/1/send",
        "method": "POST",
        "rel": "send"
    }, {
        "href": "https://app.emites.com.br/api/v1/batches/1/cancel",
        "method": "POST",
        "rel": "cancel"
    }, {
        "href": "https://app.emites.com.br/api/v1/batches/1/history",
        "method": "GET",
        "rel": "history"
    }, {
        "href": "https://app.emites.com.br/batches/show/1"
        "method": "GET"
        "rel": "html"
    }],
    "id": 1,
    "name": "batch-name",
    "emitter_id": 1,
    "status": "created",
    "properties": {
        "created": 0,
        "scheduled": 0,
        "processing": 0,
        "accepted": 0,
        "rejected": 0,
        "cancelled": 0,
        "cancelling": 0
        "total": 0
    }
}

Listagem de NFSe

Para listar todas as NFSe que pertencem a um lote em questão:

GET /api/v1/batches/1/nfse

Você também pode filtrar a listagem de notas por status:

GET /api/v1/batches/1/nfse?status=created

Cabeçalho de exemplo 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 de exemplo da resposta:

{
    "count": 1,
    "next": null,
    "previous": null,
    "collection": [{
        "_links": [{
            "href": "https://app.emites.com.br/api/v1/nfse/1",
            "method": "GET",
            "rel": "self"
        }, {
            "href": "https://app.emites.com.br/api/v1/nfse/1",
            "method": "DELETE",
            "rel": "destroy"
        }, {
            "href": "https://app.emites.com.br/api/v1/nfse/1/status",
            "method": "GET",
            "rel": "status"
        }, {
            "href": "https://app.emites.com.br/api/v1/nfse/1/cancel",
            "method": "POST",
            "rel": "cancel"
        }, {
            "href": "https://app.emites.com.br/api/v1/nfse/1/mirror",
            "method": "GET",
            "rel": "mirror"
        }, {
            "href": "https://app.emites.com.br/api/v1/nfse/1/xml",
            "method": "GET",
            "rel": "xml"
        }, {
            "href": "https://app.emites.com.br/api/v1/nfse/1/pdf",
            "method": "GET",
            "rel": "pdf"
        }, {
            "href": "https://app.emites.com.br/api/v1/nfse/1/history",
            "method": "GET",
            "rel": "history"
        }, {
            "href": "https://app.emites.com.br/api/v1/batches/1",
            "method": "GET",
            "rel": "batch"
        }, {
            "href": "https://app.emites.com.br/nfse/show/1"
            "method": "GET"
            "rel": "html"
        }],
        "errors": [],
        "service_values": {
            "service_value": "99.90",
            "deduction_value": "0.00",
            "retained_iss": false,
            "calculation_base": "99.90",
            "iss_percentage": "5.00",
            "pis_value": "0.00",
            "cofins_value": "0.00",
            "inss_value": "0.00",
            "ir_value": "0.00",
            "csll_value": "0.00",
            "discount_conditioning_value": "0.00",
            "service_item_code": "0105",
            "cnae_code": null,
            "description": "Servicos de informatica",
            "city_code": 3304557,
            "nfse_liquid_value": "109.90",
            "city_tax_code": "010501",
            "other_retentions": null,
            "retained_iss_value": null,
            "unconditioned_discount": null},
            "substitute_rps": null,
            "environment": "sandbox",
        "taker": {
            "cnpj": null,
            "fancy_name": null,
            "city_inscription": "92708711",
            "substitute_state_inscription": null,
            "state_inscription": null,
            "social_reason":
            "Razão Social do Tomador",
            "cpf": "44423739577",
            "special_situation": 0,
            "foreign_taker": false,
            "address": {
                "neighborhood": "São Pelegrino",
                "country_abbreviation": "BR",
                "reference_point": null,
                "complement": null,
                "number": "535",
                "neighborhood_type": "COM",
                "street": "Feijó Júnior",
                "country_code": "01058",
                "city": "Caxias do Sul",
                "country": "BR",
                "state": "RS",
                "street_type": "RUA",
                "city_code": 4305108,
                "zip_code": 95110550
            },
            "contact": {
                "phone": "32272144",
                "email": null
            },
        },
        "emitter_id": 7,
        "batch_id": 10,
        "xml_url": null,
        "pdf_url": null,
        "id": 12,
        "status": "scheduled",
        "description": "Agendado o processamento da NFSe",
        "nfse_key": null,
        "nfse_number": null,
        "number": 321000174,
        "serie": "a",
        "rps_type": 1,
        "emission_date": "2014-05-04T08:34:56Z",
        "operation_nature": 1,
        "national_simple_optant": false,
        "cultural_promoter": false,
        "rps_situation": 1,
        "other_informations": null,
        "competence": null,
        "special_regime": null,
        "emitter_city_code": 3304557
    }]
}

Envio

Quando um lote é enviado, a ação é aplicada em todas as NFSe pertencentes ao lote. Mesmo assim, ainda é possível consultar o status e os detalhes de cada documento separadamente.

POST /api/v1/batches/1/send

Cabeçalho de exemplo da resposta:

Status Code: 202
Date: Tue, 04 Feb 2014 17:55:19 GMT
Vary: Accept, Cookie
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
{
    "_links": [{
        "href": "https://app.emites.com.br/api/v1/batches/1",
        "method": "GET",
        "rel": "self"
    }, {
        "href": "https://app.emites.com.br/api/v1/batches/1/nfse",
        "method": "GET",
        "rel": "nfse"
    }, {
        "href": "https://app.emites.com.br/api/v1/batches/1/send",
        "method": "POST",
        "rel": "send"
    }, {
        "href": "https://app.emites.com.br/api/v1/batches/1/cancel",
        "method": "POST",
        "rel": "cancel"
    }, {
        "href": "https://app.emites.com.br/api/v1/batches/1/history",
        "method": "GET",
        "rel": "history"
    }, {
        "href": "https://app.emites.com.br/batches/show/1"
        "method": "GET"
        "rel": "html"
    }],
    "id": 1,
    "name": "batch-name",
    "emitter_id": 1,
    "status": "scheduled",
    "properties": {
        "created": 0,
        "scheduled": 1,
        "processing": 0,
        "accepted": 0,
        "rejected": 0,
        "cancelled": 0,
        "cancelling": 0
        "total": 1
    }
}

Cancelamento

Semelhante ao envio, o cancelamente também age sobre todas as NFSe do lote.

POST /api/v1/batches/1/cancel

Cabeçalho de exemplo da resposta:

Status Code: 202
Date: Tue, 04 Feb 2014 17:55:19 GMT
Vary: Accept, Cookie
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
{
    "_links": [{
        "href": "https://app.emites.com.br/api/v1/batches/1",
        "method": "GET",
        "rel": "self"
    }, {
        "href": "https://app.emites.com.br/api/v1/batches/1/nfse",
        "method": "GET",
        "rel": "nfse"
    }, {
        "href": "https://app.emites.com.br/api/v1/batches/1/send",
        "method": "POST",
        "rel": "send"
    }, {
        "href": "https://app.emites.com.br/api/v1/batches/1/cancel",
        "method": "POST",
        "rel": "cancel"
    }, {
        "href": "https://app.emites.com.br/api/v1/batches/1/history",
        "method": "GET",
        "rel": "history"
    }, {
        "href": "https://app.emites.com.br/batches/show/1"
        "method": "GET"
        "rel": "html"
    }],
    "id": 1,
    "name": "batch-name",
    "emitter_id": 1,
    "status": "scheduled",
    "properties": {
        "created": 0,
        "scheduled": 1,
        "processing": 0,
        "accepted": 0,
        "rejected": 0,
        "cancelled": 0,
        "cancelling": 0
        "total": 1
    }
}

Histórico

O histórico é o registro de toda e qualquer interação feita através da API de Batches. No registro é salvo os dados do usuário que realizou a ação bem como os seus dados.

Para consultar o histórico do batch:

GET /api/v1/batches/1/history

Cabeçalho de exemplo da resposta:

Status Code: 200
Date: Tue, 20 May 2014 12:43:23 GMT
Vary: Accept, Cookie
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
{
    "count": 4,
    "next": null,
    "previous": null,
    "collection": [{
            "emitter": {
                "id": 1,
                "social_reason":
                "Myfinance Consultoria e Informática Ltda"
            },
            "account": {
                "id": 3,
                "name": "Pull4up-NFSE"
            },
            "batch": {
                "id": 1,
                "name": "batch-name"
            },
            "id": 94,
            "token": "B2A5C4ED68C30DA895D6291448589D37",
            "from_status": null,
            "to_status":
            "created",
            "date": "2014-05-20T12:43:23.802Z"
        }, {
            "emitter": {
                "id": 1,
                "social_reason": "Myfinance Consultoria e Informática Ltda"
            },
            "account": {
                "id": 3,
                "name": "Pull4up-NFSE"
            },
            "batch": {
                "id": 1,
                "name": "batch-name"
            },
            "id": 97,
            "token": "B2A5C4ED68C30DA895D6291448589D37",
            "from_status": "created",
            "to_status": "scheduled",
            "date": "2014-05-20T13:27:19.769Z"
        }, {
            "emitter": {
                "id": 1,
                "social_reason": "Myfinance Consultoria e Informática Ltda"
            },
            "account": {
                "id": 3,
                "name": "Pull4up-NFSE"
            },
            "batch": {
                "id": 1,
                "name": "batch-name"
            },
            "id": 99,
            "token": "B2A5C4ED68C30DA895D6291448589D37",
            "from_status": "scheduled",
            "to_status": "processing",
            "date": "2014-05-20T13:27:40.530Z"
        }, {
            "emitter": {
                "id": 1,
                "social_reason": "Myfinance Consultoria e Informática Ltda"
            },
            "account": {
                "id": 3,
                "name": "Pull4up-NFSE"
            },
            "batch": {
                "id": 1,
                "name": "batch-name"
            },
            "id": 101,
            "token": "B2A5C4ED68C30DA895D6291448589D37",
            "from_status": "processing",
            "to_status": "processed",
            "date": "2014-05-20T13:29:11.070Z"
        }
    ]
}

Status do Lote

Status do lote:

Status Descrição
created O lote foi criado e está aguardando o envio pelo usuário
scheduled Enviado, aguardando o a Sefaz iniciar o processamento do lote
processing A Sefaz está processando o lote
processed O lote foi processado com sucesso, consulte as propriedades do lote para saber se as NFSe foram aceitas, rejeitadas ou canceladas

Definição do status de um lote:

Um lote só terá o status ´processed´ caso todas as NFSe desse lote já tiverem sido processadas. Caso uma única NFSe ainda esteja em processamento, o status do lote será ´processing´.