Para criar documentos deve usar o parâmetro apicall CREATE. A chamada aceita os seguintes documentos: factura, factura-recibo e proforma.
| Parâmetro | Subparâmetro | Descrição |
|---|---|---|
| apicall | Metódo de chamada do api {CREATE} | |
| apikey | Chave API de cada utilizador do software, em formato de 32 digítos. | |
| document | Parâmetro que contem informações principais sobre o documento, deve conter 9 subparâmetros com a informação do documento a criar | |
| document | type | Tipo de documento Formato: {factura,factura-recibo ou proforma} |
| document | date | Data do documentoFormato: {yyyy-mm-dd} Validação: Formato de data deve ser válido, A data do documento a criar não pode ser inferior a data do último documento |
| document | duedate | Data de vencimento do documento Formato: {yyyy-mm-dd} Validação: Formato de data deve ser válido, A data de vencimento não pode ser inferior a data do documento a criar |
| document | vref | Valor de refêrencia Formato: {alphanúmerico} Nota: Valor de parâmetro não é obrigatório |
| document | serie | Número de série do documento Formato: {alphanúmerico} Validação: O número de série deve ser o valor do ano corrente ou estar pré-definido nas configurações do utilizador. |
| document | currency | Moeda monetária do documento Formato: {Consulte aqui os formatos aceites para a moeda monetária} Validação: Formato da moeda deve ser válido Nota: Predefinir o valor 'AOA' para moeda nacional angolana |
| document | exchange_rate | Câmbio da moeda monetária do documento Formato: {númerico} Validação: Formato númerico deve ser válido Nota: Predefinir o valor '0' para moeda nacional angolana |
| document | observation | Observações relacionadas ao documento Formato: {alphanúmerico} Nota: Valor de parâmetro não é obrigatório |
| document | retention | Valor de retenção do documento Formato: {númerico} Validação: Formato númerico deve ser válido |
| client | Parâmetro que contem informações do cliente, deve conter 7 subparâmetros com a informação do cliente Nota: Ao adicionar ao documento um cliente já existente somente o valor do parâmetro 'name' é obrigatório, caso deseja adicionar um cliente não existente precisa preencher os valores ao parâmetro 'name','address','city','country' | |
| client | name | Nome do cliente a adicionar ao documento Formato: {alphanúmerico} |
| client | nif | Número de contribuinte do cliente Formato: {númerico} Validação: Formato númerico deve ser válido Nota: Valor de parâmetro não é obrigatório |
| client | Email do cliente Formato: {alphanúmerico} Validação: Formato de email deve ser válido Nota: Valor de parâmetro não é obrigatório | |
| client | city | Endereço da cidade do cliente Formato: {alphanúmerico} Nota: Valor de parâmetro não é obrigatório para clientes já existentes |
| client | address | Endereço fisíco do cliente Formato: {alphanúmerico} Nota: Valor de parâmetro não é obrigatório para clientes já existentes |
| client | postalcode | Caixa postal do cliente Formato: {alphanúmerico} Nota: Valor de parâmetro não é obrigatório |
| client | country | Endereço de pais do clienteFormato: {alphanúmerico} Nota: Valor de parâmetro não é obrigatório para clientes já existentes |
| items | Parâmetro que contem informações dos items Nota: Este parâmetro deve conter um 'array' com os dados dos items, notar que o utilizador pode adicionar vários items ao documento, para o parâmetro 'items' o array deve conter 8 subparâmetros com a informação dos items | |
| items | itemcode | Código do itemFormato: {alphanúmerico} Nota: Para adicionar ao documento um item já existente deve usar o Código do item existente caso não a API cria um novo item |
| items | description | Descrição do item Formato: {alphanúmerico} |
| items | price | Preço do item Formato: {númerico} Validação: Formato númerico deve ser válido, Formato de valor decimal não deve conter virgula, apenas ponto (.) |
| items | quantity | Quantidade do itemFormato: {númerico} Validação: Formato númerico deve ser válido |
| items | tax | Taxa/IVA do itemFormato: {númerico} Validação: Formato númerico deve ser válido, O valor da taxa/iva de ser entre 0 - 100 % Nota: Para isenção de taxa (0%) deve atribuir o valor ao Código de motivo de isenção, parâmetro ('exemption_code'), para valores acima (0%) não deve atribuir o Código de motivo de isenção |
| items | discount | Desconto to itemFormato: {númerico} Validação: Formato númerico deve ser válido, O valor do desconto deve ser entre 0 - 100 % |
| items | exemption_code | Código de Motivo de isenção de Taxa do itemFormato: {Consulte aqui a lista de Códigos de motivos de isenção de taxa} Nota: Deve atribuir o Código de isenção de taxa somente se o item for exempto de taxa, sendo o seu valor (0%) |
| items | retention | Valor de retenção do itemFormato: {númerico,boolean} Validação: Deve usar apenas '0' para 'não Aplicar' e '1' para 'Aplicar' Nota: Valor de parâmetro somente obrigatório para criação de novos items |
| items | unit | Valor de unidade do itemFormato: {texto} Validação: Deve usar apenas 'unidade' ou 'serviço' Nota: Valor de parâmetro somente obrigatório para criação de novos items |
| Parâmetro | Subparâmetro | Descrição |
|---|---|---|
| result | Resultado da operação Formato: {success,failure} | |
| message | Mensagem retornada pela API | |
| data | Retorna o valor de refêrencia (ID único) do documento criado, valor retornado somente se a operação foi realizada com successoFormato: {númerico} |
Formatos de dados aceites pela API
| Moeda monetária | Formato |
|---|---|
| Afghan afghani (AFN) | AFN |
| Albanian lek (ALL) | ALL |
| Algerian dinar (DZD) | DZD |
| Angolan kwanza (AOA) | AOA |
| Argentine peso (ARS) | ARS |
| Armenian dram (AMD) | AMD |
| Aruban florin (AWG) | AWG |
| Azerbaijani manat (AZN) | AZN |
| Bahraini dinar (BHD) | BHD |
| Bangladeshi taka (BDT) | BDT |
| Barbadian dollar (BBD) | BBD |
| Belarusian ruble (BYR) | BYR |
| Belize dollar (BZD) | BZD |
| Bermudian dollar (BMD) | BMD |
| Bhutanese ngultrum (BTN) | BTN |
| Brazilian real (BRL) | BRL |
| Bulgarian lev (BGN) | BGN |
| Burundian franc (BIF) | BIF |
| Cambodian riel (KHR) | KHR |
| Canadian dollar (CAD) | CAD |
| Cape Verdean escudo (CVE) | CVE |
| Cayman Islands dolla (KYD) | KYD |
| Chilean peso (CLP) | CLP |
| Chinese yuan (CNY) | CNY |
| Colombian peso (COP) | COP |
| Comorian franc (KMF) | KMF |
| Costa Rican colon (CRC) | CRC |
| Croatian kuna (HRK) | HRK |
| Cuban convertible pe (CUC) | CUC |
| Czech koruna (CZK) | CZK |
| Djiboutian franc (DJF) | DJF |
| Dominican peso (DOP) | DOP |
| Egyptian pound (EGP) | EGP |
| Eritrean nakfa (ERN) | ERN |
| Ethiopian birr (ETB) | ETB |
| Danish krone (DKK) | DKK |
| Fijian dollar (FJD) | FJD |
| Central African CFA (XAF) | XAF |
| Georgian lari (GEL) | GEL |
| Ghana cedi (GHS) | GHS |
| Gibraltar pound (GIP) | GIP |
| Guatemalan quetzal (GTQ) | GTQ |
| Guinean franc (GNF) | GNF |
| Guyanese dollar (GYD) | GYD |
| Haitian gourde (HTG) | HTG |
| Honduran lempira (HNL) | HNL |
| Hong Kong dollar (HKD) | HKD |
| Hungarian forint (HUF) | HUF |
| Icelandic krona (ISK) | ISK |
| Indian rupee (INR) | INR |
| Indonesian rupiah (IDR) | IDR |
| Iraqi dinar (IQD) | IQD |
| Israeli new shekel (ILS) | ILS |
| Jamaican dollar (JMD) | JMD |
| Japanese yen (JPY) | JPY |
| Jordanian dinar (JOD) | JOD |
| Kazakhstani tenge (KZT) | KZT |
| Kenyan shilling (KES) | KES |
| Kuwaiti dinar (KWD) | KWD |
| Kyrgyzstani som (KGS) | KGS |
| Lao kip (LAK) | LAK |
| Lebanese pound (LBP) | LBP |
| Lesotho loti (LSL) | LSL |
| Liberian dollar (LRD) | LRD |
| Malagasy ariary (MGA) | MGA |
| Malawian kwacha (MWK) | MWK |
| Malaysian ringgit (MYR) | MYR |
| Maldivian rufiyaa (MVR) | MVR |
| Mauritanian ouguiya (MRO) | MRO |
| Mauritian rupee (MUR) | MUR |
| Mexican peso (MXN) | MXN |
| Moldovan leu (MDL) | MDL |
| Mongolian togrog (MNT) | MNT |
| Moroccan dirham (MAD) | MAD |
| Mozambican metical (MZN) | MZN |
| Burmese kyat (MMK) | MMK |
| Namibian dollar (NAD) | NAD |
| Nepalese rupee (NPR) | NPR |
| Nicaraguan cordoba (NIO) | NIO |
| Nigerian naira (NGN) | NGN |
| New Zealand dollar (NZD) | NZD |
| Norwegian krone (NOK) | NOK |
| Omani rial (OMR) | OMR |
| Pakistani rupee (PKR) | PKR |
| Panamanian balboa (PAB) | PAB |
| Papua New Guinean ki (PGK) | PGK |
| Paraguayan guarani (PYG) | PYG |
| Peruvian nuevo sol (PEN) | PEN |
| Philippine peso (PHP) | PHP |
| Polish Zloty (PLN) | PLN |
| Euro (EUR) | EUR |
| Qatari riyal (QAR) | QAR |
| Romanian leu (RON) | RON |
| Russian ruble (RUB) | RUB |
| Rwandan franc (RWF) | RWF |
| East Caribbean dolla (XCD) | XCD |
| Samoan Tala (WST) | WST |
| Saudi riyal (SAR) | SAR |
| Serbian dinar (RSD) | RSD |
| Seychellois rupee (SCR) | SCR |
| Sierra Leonean leone (SLL) | SLL |
| Brunei dollar (BND) | BND |
| Solomon Islands doll (SBD) | SBD |
| Somali shilling (SOS) | SOS |
| South African rand (ZAR) | ZAR |
| Sri Lankan rupee (LKR) | LKR |
| Sudanese pound (SDG) | SDG |
| Surinamese dollar (SRD) | SRD |
| Swazi lilangeni (SZL) | SZL |
| Swedish krona (SEK) | SEK |
| Swiss franc (CHF) | CHF |
| New Taiwan dollar (TWD) | TWD |
| Tajikistani somoni (TJS) | TJS |
| Thai baht (THB) | THB |
| West African CFA fra (XOF) | XOF |
| Tongan pa?anga (TOP) | TOP |
| Trinidad and Tobago (TTD) | TTD |
| Tunisian dinar (TND) | TND |
| Turkish lira (TRY) | TRY |
| Turkmenistan manat (TMT) | TMT |
| Australian dollar (AUD) | AUD |
| Ugandan shilling (UGX) | UGX |
| Ukrainian hryvnia (UAH) | UAH |
| United Arab Emirates (AED) | AED |
| British pound (GBP) | GBP |
| United States dollar (USD) | USD |
| Uruguayan peso (UYU) | UYU |
| Uzbekistani som (UZS) | UZS |
| Vanuatu vatu (VUV) | VUV |
| Vietnamese (VND) | VND |
| CFP franc (XPF) | XPF |
| Yemeni rial (YER) | YER |
| Zambian kwacha (ZMW) | ZMW |
| Botswana pula (BWP) | BWP |
| Motivos de isenção | Formato |
|---|---|
| Regime Simplificado | M00 |
| Transmissão de bens e serviço não sujeita | M02 |
| IVA - Regime de exclusão | M04 |
| Isento nos termos da alínea a) do nº1 do artigo 12º do CIVA | M10 |
| Isento nos termos da alínea b) do nº1 do artigo 12º do CIVA | M11 |
| Isento nos termos da alínea c) do nº1 do artigo 12º do CIVA | M12 |
| Isento nos termos da alínea d) do nº1 do artigo 12º do CIVA | M13 |
| Isento nos termos da alínea e) do nº1 do artigo 12º do CIVA | M14 |
| Isento nos termos da alínea f) do nº1 do artigo 12º do CIVA | M15 |
| Isento nos termos da alínea g) do nº1 do artigo 12º do CIVA | M16 |
| Isento nos termos da alínea h) do nº1 do artigo 12º do CIVA | M17 |
| Isento nos termos da alínea i) do nº1 do artigo 12º do CIVA | M18 |
| Isento nos termos da alínea j) do nº1 do artigo 12º do CIVA | M19 |
| Isento nos termos da alínea k) do nº1 do artigo 12º do CIVA | M20 |
| Isento nos termos da alínea l) do nº1 do artigo 12º do CIVA | M21 |
| Isento nos termos da alínea m) do nº1 do artigo 12º do CIVA | M22 |
| Isento nos termos da alínea n) do nº1 do artigo 12º do CIVA | M23 |
| Isento nos termos da alínea o) do nº1 do artigo 12º do CIVA | M24 |
| Isento nos termos da alínea a) do nº1 do artigo 15º do CIVA | M30 |
| Isento nos termos da alínea b) do nº1 do artigo 15º do CIVA | M31 |
| Isento nos termos da alínea c) do nº1 do artigo 15º do CIVA | M32 |
| Isento nos termos da alínea d) do nº1 do artigo 15º do CIVA | M33 |
| Isento nos termos da alínea e) do nº1 do artigo 15º do CIVA | M34 |
| Isento nos termos da alínea f) do nº1 do artigo 15º do CIVA | M35 |
| Isento nos termos da alínea g) do nº1 do artigo 15º do CIVA | M36 |
| Isento nos termos da alínea h) do nº1 do artigo 15º do CIVA | M37 |
| Isento nos termos da alínea i) do nº1 do artigo 15º do CIVA | M38 |
| Isento nos termos da alínea a) do nº1 do artigo 14º do CIVA | M80 |
| Isento nos termos da alínea b) do nº1 do artigo 14º do CIVA | M81 |
| Isento nos termos da alínea c) do nº1 do artigo 14º do CIVA | M82 |
| Isento nos termos da alínea d) do nº1 do artigo 14º do CIVA | M83 |
| Isento nos termos da alínea e) do nº1 do artigo 14º do CIVA | M84 |
| Isento nos termos da alínea a) do nº2 do artigo 14º do CIVA | M85 |
| Isento nos termos da alínea b) do nº2 do artigo 14º do CIVA | M86 |
| Isento nos termos da alínea a) do nº1 do artigo 16º do CIVA | M90 |
| Isento nos termos da alínea b) do nº1 do artigo 16º do CIVA | M91 |
| Isento nos termos da alínea c) do nº1 do artigo 16º do CIVA | M92 |
| Isento nos termos da alínea d) do nº1 do artigo 16º do CIVA | M93 |
| Isento nos termos da alínea e) do nº1 do artigo 16º do CIVA | M94 |
Este exemplo mostra como criar um novo documento com 2 items
{
"apicall":"CREATE",
"apikey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"document": {
"type": "factura-recibo",
"date": "2020-01-01",
"duedate": "2020-01-31",
"vref": "",
"serie":"2020",
"currency":"AOA",
"exchange_rate":"0",
"observation":"",
"retention":"0"
},
"client":{
"name": "SeaFoodConsultants",
"nif": "5402102791",
"email": "operatinos@seafoodconsultants.com",
"city": "Luanda",
"address":"Av Fidel Castro",
"postalcode":"",
"country":"Angola"
},
"items": [
{
"itemcode": "FSHBX10",
"description": "Caixa de Pescado 10Kg",
"price": "25000",
"quantity": "1",
"tax": "14",
"discount": "0",
"exemption_code": "",
"retention": "",
"unit": "Unidade"
},
{
"itemcode": "FSHBX20",
"description": "Caixa de Pescado 20Kg",
"price": "40000",
"quantity": "2",
"tax": "14",
"discount": "0",
"exemption_code": "",
"retention": "",
"unit": "Serviço"
}
]
}