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