{ "openapi": "3.1.0", "info": { "title": "InvoiceXpress API", "description": "Endpoints for managing Accounts, Invoices, Estimates, and organization data in InvoiceXpress.

Welcome to our API in JSON

Hello there! Welcome to the world of InvoiceXpress API! This world is inhabitated by creatures we call Endpoints.

People and Endpoints live together by supporting each other. Some people play with Endpoints, some work with them.

If you’re reading this, let me guess, you need to issue invoices but don’t want to lose focus from building a great solution and writing amazing code.

Did we cover your scenario? Ok, great. Let’s do this.

Quick Start

  1. [Sign up FREE for 30 days](https://web.invoicexpress.com/signup)
  2. [Get your API key](https://web.invoicexpress.com/users/api_key)
  3. [Create an Invoice](#tag/Invoices)
\n## Documentation\n\nReference tables for Portuguese VAT (IVA) exemptions, payment mechanism codes used for partial payments, and accepted countries when creating a client or an account.\n\n
\nAuthentication\n\n\nIn order to authenticate a user through our API, an API key must be used. All API endpoints are available via HTTPS. HTTP access is denied. Each API key authenticates a user inside an account, and it's composed by arbitrary characters.\n\nThis key must be passed on the query string in each HTTPS request to authenticate the user. Although all endpoints are accessed through HTTPS, please keep this token as secure as possible in order to avoid third party's to access your InvoiceXpress data.\n\nWe strongly recommend you re-generate your API Key from time to time.\n\n**Example:**\n\n`https://ACCOUNT_NAME.app.invoicexpress.com/invoices.json?api_key=API_KEY`\n\nYou can find your ACCOUNT_NAME and API_KEY here: [https://www.app.invoicexpress.com/users/api](https://www.app.invoicexpress.com/users/api)\n\nOn POST and PUT requests do not forget to specify on the Header:\n\n`Content-Type: application/json`\n\n\n
\n\n
\nIVA exemption codes\n\n\n| Code | Description on the Invoice | Where does it apply? |\n| --- | --- | --- |\n| M01 | Artigo 16.°, n.° 6 do CIVA | Artigo 16.°, n.° 6, alíneas a) a d) do CIVA |\n| M02 | Artigo 6.° do Decreto-Lei n.° 198/90, de 19 de junho | Artigo 6.° do Decreto-Lei n.° 198/90, de 19 de junho |\n| M04 | Isento artigo 13.° do CIVA | Artigo 13.° do CIVA |\n| M05 | Isento artigo 14.° do CIVA | Artigo 14.° do CIVA |\n| M06 | Isento artigo 15.° do CIVA | Artigo 15.° do CIVA |\n| M07 | Isento artigo 9.° do CIVA | Artigo 9.° do CIVA |\n| M09 | IVA – não confere direito a dedução | Artigo 62.° alínea b) do CIVA |\n| M10 | IVA – regime de isenção | Artigo 57.° do CIVA |\n| M11 | Regime particular do tabaco | Decreto-Lei n.° 346/85, de 23 de agosto |\n| M12 | Regime da margem de lucro – Agências de viagens | Decreto-Lei n.° 221/85, de 3 de julho |\n| M13 | Regime da margem de lucro – Bens em segunda mão | Decreto-Lei n.° 199/96, de 18 de outubro |\n| M14 | Regime da margem de lucro – Objetos de arte | Decreto-Lei n.° 199/96, de 18 de outubro |\n| M15 | Regime da margem de lucro – Objetos de coleção e antiguidades | Decreto-Lei n.° 199/96, de 18 de outubro |\n| M16 | Isento artigo 14.° do RITI | Artigo 14.° do RITI |\n| M19 | Outras isenções | Isenções temporárias determinadas em diploma próprio |\n| M20 | IVA – regime forfetário | Artigo 59.°-D n.°2 do CIVA |\n| M21 | IVA – não confere direito à dedução (ou expressão similar) | Artigo 72.° n.° 4 do CIVA |\n| M25 | Mercadorias à consignação | Artigo 38.° n.° 1 alínea a) |\n| M30 | IVA – autoliquidação | Artigo 2.° n.° 1 alínea i) do CIVA |\n| M31 | IVA – autoliquidação | Artigo 2.° n.° 1 alínea j) do CIVA |\n| M32 | IVA – autoliquidação | Artigo 2.° n.° 1 alínea I) do CIVA |\n| M33 | IVA – autoliquidação | Artigo 2.° n.° 1 alínea m) do CIVA |\n| M35 | IVA – autoliquidação | Decreto-Lei n.º 97/2026, de 20 de maio. |\n| M40 | IVA – autoliquidação | Artigo 6.° n.° 6 alínea a) do CIVA, a contrário |\n| M41 | IVA – autoliquidação | Artigo 8.° n.° 3 do RITI |\n| M42 | IVA – autoliquidação | Decreto-Lei n.° 21/2007, de 29 de janeiro |\n| M43 | IVA – autoliquidação | Decreto-Lei n.° 362/99, de 16 de setembro |\n| M44 | IVA - Regras específicas - artigo 6.º | Artigo 6.º do CIVA – Regras específicas. A utilizar nas operações que não sejam localizadas em Portugal por força das regras de exceção constantes dos números 7 e seguintes do artigo 6.º do Código do IVA |\n| M45 | IVA - Regime transfronteiriço de isenção | Artigo 58.º-A do CIVA. A utilizar nas operações localizadas noutro Estado Membro da União Europeia e que ali fiquem isentas de IVA, em virtude de o transmitente dos bens ou prestador dos serviços ter aderido ao Regime Transfronteiriço de isenção relativamente às operações que realize nesse Estado Membro. Sem prejuízo do disposto no Ofício-Circulado n.º 25 065, de 08/04/2025, por uma questão de melhor identificação e separação destas operações, deve ser utilizada a menção \"IVA – regime transfronteiriço de isenção\". |\n| M46 | IVA - e-TaxFree | Decreto-lei n.º 19/2017, de 14 de fevereiro. A utilizar pelo vendedor na emissão de faturas relativas a operações em que tenha aplicado a isenção na transmissão de bens a serem transportados na bagagem pessoal de viajantes sem domicílio ou estabelecimento na União Europeia, nos termos do referido decreto-lei. |\n| M99 | Não sujeito ou não tributado | Outras situações de não liquidação do imposto (Exemplos: artigo 2.°, n.° 2 ; artigo 3.°, n.°s 4, 6 e 7; artigo 4.°, n.° 5, todos do CIVA) |\n\n\n
\n\n
\nPayment mechanisms\n\n\nThis list shows the possible values for the payment mechanism when doing a partial payment:\n\n- **CC**: Credit card\n- **CD**: Debit card\n- **CH**: Bank check\n- **CO**: Check or voucher\n- **CS**: Current account balance compensation\n- **DE**: e-Cash\n- **LC**: Commercial paper\n- **MB**: Multibanco payment references\n- **NU**: Cash\n- **OU**: Other methods not mentioned here\n- **PR**: Exchange of properties\n- **TB**: Bank transfer or authorized direct debit\n- **TR**: Restaurant ticket\n\n\n
\n\n
\nCountry list\n\n\nThis list shows the countries accepted when creating a client or an account:\n- Portugal\n- Ireland\n- UK\n- Canada\n- United States\n- Afghanistan\n- Albania\n- Algeria\n- American Samoa\n- Andorra\n- Angola\n- Anguilla\n- Antigua and Barbuda\n- Argentina\n- Armenia\n- Aruba\n- Australia\n- Austria\n- Azerbaijan\n- Bahamas\n- Bahrain\n- Bangladesh\n- Barbados\n- Belarus\n- Belgium\n- Belize\n- Benin\n- Bermuda\n- Bhutan\n- Bolivia\n- Bosnia-Herzegovina\n- Botswana\n- Brazil\n- British Indian Ocean Territory\n- Brunei\n- Bulgaria\n- Burkina Faso\n- Burma\n- Burundi\n- Cambodia\n- Cameroon\n- Canton and Enderbury Islands\n- Cape Verde\n- Cayman Islands\n- Central African Republic\n- Chad\n- Chile\n- China\n- Christmas Island\n- Cocos (Keeling) Islands\n- Colombia\n- Comoros\n- Congo\n- Congo, Democratic Republic\n- Cook Islands\n- Costa Rica\n- Côte d’Ivoire\n- Croatia\n- Cuba\n- Curaçao\n- Cyprus\n- Czech Republic\n- Denmark\n- Djibouti\n- Dominica\n- Dominican Republic\n- Dronning Maud Land\n- East Timor\n- Ecuador\n- Egypt\n- El Salvador\n- Equatorial Guinea\n- Eritrea\n- Estonia\n- Ethiopia\n- Faeroe Islands (Føroyar)\n- Falkland Islands\n- Fiji\n- Finland\n- France\n- French Guiana\n- French Polynesia\n- Gabon\n- Gambia\n- Georgia\n- Germany\n- Ghana\n- Gibraltar\n- Great Britain\n- Greece\n- Greenland\n- Grenada\n- Guadeloupe\n- Guam\n- Guatemala\n- Guernsey\n- Guinea-Bissau\n- Guinea\n- Guyana\n- Haiti\n- Heard and McDonald Islands\n- Honduras\n- Hong Kong\n- Hungary\n- Iceland\n- India\n- Indonesia\n- International Monetary Fund\n- Iran\n- Iraq\n- Isle of Man\n- Israel\n- Italy\n- Ivory Coast\n- Jamaica\n- Japan\n- Jersey\n- Johnston Island\n- Jordan\n- Kampuchea\n- Kazakhstan\n- Kenya\n- Kiribati\n- Korea, North\n- Korea, South\n- Kuwait\n- Kyrgyzstan\n- Laos\n- Latvia\n- Lebanon\n- Lesotho\n- Liberia\n- Libya\n- Liechtenstein\n- Lithuania\n- Luxembourg\n- Macau\n- Macedonia (Former Yug. Rep.)\n- Madagascar\n- Malawi\n- Malaysia\n- Maldives\n- Mali\n- Malta\n- Marshall Islands\n- Martinique\n- Mauritania\n- Mauritius\n- Mayotte\n- Micronesia\n- Midway Islands\n- Mexico\n- Moldova\n- Monaco\n- Mongolia\n- Montenegro\n- Montserrat\n- Morocco\n- Mozambique\n- Myanmar\n- Nauru\n- Namibia\n- Nepal\n- Netherlands Antilles\n- Netherlands\n- New Caledonia\n- New Zealand\n- Nicaragua\n- Niger\n- Nigeria\n- Niue\n- Norfolk Island\n- Northern Mariana Islands\n- Norway\n- Oman\n- Pakistan\n- Palau\n- Palestine\n- Panama\n- Papua New Guinea\n- Paraguay\n- Peru\n- Philippines\n- Pitcairn Island\n- Poland\n- Puerto Rico\n- Qatar\n- Reunion\n- Romania\n- Russia\n- Rwanda\n- Samoa (Western)\n- Samoa (America)\n- San Marino\n- São Tomé and Príncipe\n- Saudi Arabia\n- Sénégal\n- Serbia\n- Seychelles\n- Sierra Leone\n- Singapore\n- Slovakia\n- Slovenia\n- Solomon Islands\n- Somalia\n- South Africa\n- Spain\n- Sri Lanka\n- St. Helena\n- St. Kitts and Nevis\n- St. Lucia\n- St. Vincent and the Grenadines\n- Sudan\n- Suriname\n- Svalbard and Jan Mayen Islands\n- Swaziland\n- Sweden\n- Switzerland\n- Syria\n- Tahiti\n- Taiwan\n- Tajikistan\n- Tanzania\n- Thailand\n- Timor-Leste\n- Togo\n- Trinidad and Tobago\n- Tunisia\n- Turkey\n- Turkmenistan\n- Turks and Caicos Islands\n- Tuvalu\n- Uganda\n- Ukraine\n- United Arab Emirates\n- Upper Volta\n- Uruguay\n- Uzbekistan\n- Vanuatu\n- Vatican\n- Venezuela\n- Vietnam\n- Virgin Islands\n- Wake Island\n- Wallis and Futuna Islands\n- Western Sahara\n- Western Samoa\n- Yemen\n- Zaïre\n- Zambia\n- Zimbabwe\n\n\n
\n\n
\nTaxes country codes\n\n\n| Country | Code |\n| --- | --- |\n| Portugal – Continental | PT |\n| Portugal – Açores | PT-AC |\n| Portugal – Madeira | PT-MA |\n| Afghanistan | AF |\n| Åland Islands | AX |\n| Albania | AL |\n| Algeria | DZ |\n| American Samoa | AS |\n| Andorra | AD |\n| Angola | AO |\n| Anguilla | AI |\n| Antarctica | AQ |\n| Antigua and Barbuda | AG |\n| Argentina | AR |\n| Armenia | AM |\n| Aruba | AW |\n| Australia | AU |\n| Austria | AT |\n| Azerbaijan | AZ |\n| Bahamas | BS |\n| Bahrain | BH |\n| Bangladesh | BD |\n| Barbados | BB |\n| Belarus | BY |\n| Belgium | BE |\n| Belize | BZ |\n| Benin | BJ |\n| Bermuda | BM |\n| Bhutan | BT |\n| Bolivia | BO |\n| Bosnia-Herzegovina | BA |\n| Botswana | BW |\n| Bouvet Island | BV |\n| Brazil | BR |\n| British Indian Ocean Territory | IO |\n| Brunei | BN |\n| Bulgaria | BG |\n| Burkina Faso | BF |\n| Burma | MM |\n| Burundi | BI |\n| Cambodia | KH |\n| Cameroon | CM |\n| Canada | CA |\n| Canton and Enderbury Islands | KI |\n| Cape Verde | CV |\n| Cayman Islands | KY |\n| Central African Republic | CF |\n| Chad | TD |\n| Chile | CL |\n| China | CN |\n| Christmas Island | CX |\n| Cocos (Keeling) Islands | CC |\n| Colombia | CO |\n| Comoros | KM |\n| Congo | CG |\n| Congo, Democratic Republic | CD |\n| Cook Islands | CK |\n| Costa Rica | CR |\n| Côte d’Ivoire | CI |\n| Croatia | HR |\n| Cuba | CU |\n| Cyprus | CY |\n| Czech Republic | CZ |\n| Denmark | DK |\n| Djibouti | DJ |\n| Dominica | DM |\n| Dominican Republic | DO |\n| Dronning Maud Land | AQ |\n| East Timor | TL |\n| Ecuador | EC |\n| Egypt | EG |\n| El Salvador | SV |\n| Equatorial Guinea | GQ |\n| Eritrea | ER |\n| Estonia | EE |\n| Ethiopia | ET |\n| Falkland Islands | FK |\n| Faroe Islands | FO |\n| Fiji | FJ |\n| Finland | FI |\n| France | FR |\n| French Guiana | GF |\n| French Polynesia | PF |\n| French Southern Territories | TF |\n| Gabon | GA |\n| Gambia | GM |\n| Georgia | GE |\n| Germany | DE |\n| Ghana | GH |\n| Gibraltar | GI |\n| Greece | GR |\n| Greenland | GL |\n| Grenada | GD |\n| Guadeloupe | GP |\n| Guam | GU |\n| Guatemala | GT |\n| Guernsey | GG |\n| Guinea | GN |\n| Guinea-Bissau | GW |\n| Guyana | GY |\n| Haiti | HT |\n| Heard and McDonald Islands | HM |\n| Holy See (Vatican City State) | VA |\n| Honduras | HN |\n| Hong Kong | HK |\n| Hungary | HU |\n| Iceland | IS |\n| India | IN |\n| Indonesia | ID |\n| Iran | IR |\n| Iraq | IQ |\n| Ireland | IE |\n| Isle of Man | IM |\n| Israel | IL |\n| Italy | IT |\n| Ivory Coast | CI |\n| Jamaica | JM |\n| Japan | JP |\n| Jersey | JE |\n| Johnston Island | UM |\n| Jordan | JO |\n| Kampuchea | KH |\n| Kazakhstan | KZ |\n| Kenya | KE |\n| Kiribati | KI |\n| Korea, North | KP |\n| Korea, South | KR |\n| Kuwait | KW |\n| Kyrgyzstan | KG |\n| Laos | LA |\n| Latvia | LV |\n| Lebanon | LB |\n| Lesotho | LS |\n| Liberia | LR |\n| Libya | LY |\n| Liechtenstein | LI |\n| Lithuania | LT |\n| Luxembourg | LU |\n| Macau | MO |\n| Macedonia | MK |\n| Madagascar | MG |\n| Malawi | MW |\n| Malaysia | MY |\n| Maldives | MV |\n| Mali | ML |\n| Malta | MT |\n| Marshall Islands | MH |\n| Martinique | MQ |\n| Mauritania | MR |\n| Mauritius | MU |\n| Mayotte | YT |\n| Mexico | MX |\n| Micronesia | FM |\n| Midway Islands | UM |\n| Moldova | MD |\n| Monaco | MC |\n| Mongolia | MN |\n| Montenegro | ME |\n| Montserrat | MS |\n| Morocco | MA |\n| Mozambique | MZ |\n| Myanmar | MM |\n| Namibia | NA |\n| Nauru | NR |\n| Nepal | NP |\n| Netherlands | NL |\n| Netherlands Antilles | AN |\n| New Caledonia | NC |\n| New Zealand | NZ |\n| Nicaragua | NI |\n| Niger | NE |\n| Nigeria | NG |\n| Niue | NU |\n| Norfolk Island | NF |\n| Northern Mariana Islands | MP |\n| Norway | NO |\n| Oman | OM |\n| Pakistan | PK |\n| Palau | PW |\n| Palestine | PS |\n| Panama | PA |\n| Papua New Guinea | PG |\n| Paraguay | PY |\n| Peru | PE |\n| Philippines | PH |\n| Pitcairn Island | PN |\n| Poland | PL |\n| Puerto Rico | PR |\n| Qatar | QA |\n| Reunion | RE |\n| Romania | RO |\n| Russia | RU |\n| Russian Federation | RU |\n| Rwanda | RW |\n| Saint Barthélemy | BL |\n| St. Helena | SH |\n| St. Kitts and Nevis | KN |\n| St. Lucia | LC |\n| Saint Martin | MF |\n| Saint Pierre And Miquelon | PM |\n| St. Vincent and the Grenadines | VC |\n| Samoa (America) | AS |\n| Samoa (Western) | WS |\n| San Marino | SM |\n| São Tomé and Príncipe | ST |\n| Saudi Arabia | SA |\n| Sénégal | SN |\n| Serbia | RS |\n| Seychelles | SC |\n| Sierra Leone | SL |\n| Singapore | SG |\n| Slovakia | SK |\n| Slovenia | SI |\n| Solomon Islands | SB |\n| Somalia | SO |\n| South Africa | ZA |\n| South Georgia And The South Sandwich Islands | GS |\n| Spain | ES |\n| Sri Lanka | LK |\n| Sudan | SD |\n| Suriname | SR |\n| Svalbard and Jan Mayen Islands | SJ |\n| Swaziland | SZ |\n| Sweden | SE |\n| Switzerland | CH |\n| Syria | SY |\n| Tahiti | PF |\n| Taiwan | TW |\n| Tajikistan | TJ |\n| Tanzania | TZ |\n| Thailand | TH |\n| Timor-Leste | TL |\n| Togo | TG |\n| Tokelau | TK |\n| Tonga | TO |\n| Trinidad and Tobago | TT |\n| Tunisia | TN |\n| Turkey | TR |\n| Turkmenistan | TM |\n| Turks and Caicos Islands | TC |\n| Tuvalu | TV |\n| Uganda | UG |\n| Ukraine | UA |\n| United Arab Emirates | AE |\n| United Kingdom | GB |\n| Upper Volta | BF |\n| United States | US |\n| United States Minor Outlying Islands | UM |\n| Uruguay | UY |\n| Uzbekistan | UZ |\n| Vanuatu | VU |\n| Vatican | VA |\n| Venezuela | VE |\n| Vietnam | VN |\n| Virgin Islands | VG |\n| Virgin Islands, U.S. | VI |\n| Wake Island | UM |\n| Wallis and Futuna Islands | WF |\n| Western Sahara | EH |\n| Western Samoa | WS |\n| Yemen | YE |\n| Zaïre | CD |\n| Zambia | ZM |\n| Zimbabwe | ZW |\n\n\n
\n\n
\nCurrency codes\n\n\n| Name | Symbol | Code |\n| --- | --- | --- |\n| Euro | € | EUR |\n| Pound sterling | £ | GBP |\n| Canadian dollar | C$ | CAD |\n| U.S. dollar | $ | USD |\n| Afghan afghani | ؋ | AFN |\n| Albanian lek | L | ALL |\n| Algerian dinar | د.ج | DZD |\n| Angolan kwanza | Kz | AOA |\n| Argentine peso | $ | ARS |\n| Armenian dram | դր. | AMD |\n| Aruban florin | ƒ | AWG |\n| Australian dollar | A$ | AUD |\n| Azerbaijani manat | ¤ | AZN |\n| Bahamian dollar | $ | BSD |\n| Bahraini dinar | ب.د | BHD |\n| Bangladeshi taka | ¤ | BDT |\n| Barbadian dollar | $ | BBD |\n| Belarusian ruble | Br | BYR |\n| Belize dollar | $ | BZD |\n| Bermudian dollar | $ | BMD |\n| Bhutanese ngultrum | ¤ | BTN |\n| Bolivian boliviano | Bs. | BOB |\n| Bosnia & Herzegovina mark | KM | BAM |\n| Botswana pula | P | BWP |\n| Brazilian real | R$ | BRL |\n| Brunei dollar | $ | BND |\n| Bulgarian lev | лв | BGN |\n| Burundian franc | Fr | BIF |\n| Cambodian riel | ¤ | KHR |\n| Cape Verdean escudo | Esc | CVE |\n| Cayman Islands dollar | $ | KYD |\n| Central African CFA franc | Fr | XAF |\n| CFP franc | Fr | XPF |\n| Chilean peso | $ | CLP |\n| Chinese yuan | ¥ | CNY |\n| Colombian peso | $ | COP |\n| Comorian franc | Fr | KMF |\n| Congolese franc | Fr | CDF |\n| Costa Rican colón | ₡ | CRC |\n| Croatian kuna | kn | HRK |\n| Cuban convertible peso | $ | CUC |\n| Cuban peso | $ | CUP |\n| Czech koruna | Kč | CZK |\n| Danish krone | kr. | DKK |\n| Djiboutian franc | Fr | DJF |\n| Dominican peso | $ | DOP |\n| East Caribbean dollar | $ | XCD |\n| Egyptian pound | ج.م | EGP |\n| Eritrean nakfa | Nfk | ERN |\n| Estonian kroon | KR | EEK |\n| Ethiopian birr | ¤ | ETB |\n| Falkland Islands pound | £ | FKP |\n| Fijian dollar | $ | FJD |\n| Gambian dalasi | D | GMD |\n| Georgian lari | ლ | GEL |\n| Ghanaian cedi | ₵ | GHS |\n| Gibraltar pound | £ | GIP |\n| Guatemalan quetzal | Q | GTQ |\n| Guinean franc | Fr | GNF |\n| Guyanese dollar | $ | GYD |\n| Haitian gourde | G | HTG |\n| Honduran lempira | L | HNL |\n| Hong Kong dollar | $ | HKD |\n| Hungarian forint | Ft | HUF |\n| Icelandic króna | kr | ISK |\n| Indian rupee | Rs | INR |\n| Indonesian rupiah | Rp | IDR |\n| Iranian rial | ﷼ | IRR |\n| Iraqi dinar | ع.د | IQD |\n| Israeli new sheqel | ₪ | ILS |\n| Jamaican dollar | $ | JMD |\n| Japanese yen | ¥ | JPY |\n| Jordanian dinar | د.ا | JOD |\n| Kazakhstani tenge | 〒 | KZT |\n| Kenyan shilling | Sh | KES |\n| Kuwaiti dinar | د.ك | KWD |\n| Kyrgyzstani som | ¤ | KGS |\n| Lao kip | ₭ | LAK |\n| Latvian lats | Ls | LVL |\n| Lebanese pound | ل.ل | LBP |\n| Lesotho loti | L | LSL |\n| Liberian dollar | $ | LRD |\n| Libyan dinar | ل.د | LYD |\n| Lithuanian litas | Lt | LTL |\n| Macanese pataca | P | MOP |\n| Macedonian denar | ден | MKD |\n| Malagasy ariary | ¤ | MGA |\n| Malawian kwacha | MK | MWK |\n| Malaysian ringgit | RM | MYR |\n| Maldivian rufiyaa | Rf | MVR |\n| Mauritanian ouguiya | UM | MRO |\n| Mauritian rupee | ₨ | MUR |\n| Mexican peso | $ | MXN |\n| Moldovan leu | L | MDL |\n| Mongolian tögrög | ₮ | MNT |\n| Moroccan dirham | د.م. | MAD |\n| Mozambican metical | MT | MZN |\n| Myanma kyat | Ks | MMK |\n| Namibian dollar | $ | NAD |\n| Nepalese rupee | ₨ | NPR |\n| Netherlands Antillean guilder | ƒ | ANG |\n| New Taiwan dollar | $ | TWD |\n| New Zealand dollar | $ | NZD |\n| Nicaraguan córdoba | C$ | NIO |\n| Nigerian naira | ₦ | NGN |\n| North Korean won | ₩ | KPW |\n| Norwegian krone | kr | NOK |\n| Omani rial | ر.ع. | OMR |\n| Pakistani rupee | ₨ | PKR |\n| Papua New Guinean kina | K | PGK |\n| Paraguayan guaraní | ₲ | PYG |\n| Peruvian nuevo sol | S/ | PEN |\n| Philippine peso | ₱ | PHP |\n| Polish złoty | zł | PLN |\n| Qatari riyal | ر.ق | QAR |\n| Romanian leu | lei | RON |\n| Russian ruble | ₽ | RUB |\n| Rwandan franc | Fr | RWF |\n| Saint Helena pound | £ | SHP |\n| Samoan tālā | T | WST |\n| São Tomé and Príncipe dobra | Db | STN |\n| Saudi riyal | ر.س | SAR |\n| Serbian dinar | дин. | RSD |\n| Seychellois rupee | ₨ | SCR |\n| Sierra Leonean leone | Le | SLL |\n| Singapore dollar | $ | SGD |\n| Solomon Islands dollar | $ | SBD |\n| Somali shilling | Sh | SOS |\n| South African rand | R | ZAR |\n| South Korean won | ₩ | KRW |\n| Sri Lankan rupee | Rs | LKR |\n| Sudanese pound | ج.س. | SDG |\n| Surinamese dollar | $ | SRD |\n| Swazi lilangeni | L | SZL |\n| Swedish krona | kr | SEK |\n| Swiss franc | Fr | CHF |\n| Syrian pound | ل.س. | SYP |\n| Tajikistani somoni | ЅМ | TJS |\n| Tanzanian shilling | Sh | TZS |\n| Thai baht | ฿ | THB |\n| Tongan paʻanga | T$ | TOP |\n| Trinidad and Tobago dollar | $ | TTD |\n| Tunisian dinar | د.ت | TND |\n| Turkish lira | ₺ | TRY |\n| Turkmenistan manat | m | TMT |\n| Ugandan shilling | Sh | UGX |\n| Ukrainian hryvnia | ₴ | UAH |\n| United Arab Emirates dirham | د.إ | AED |\n| Uruguayan peso | $ | UYU |\n| Uzbekistani so'm | ¤ | UZS |\n| Vanuatu vatu | Vt | VUV |\n| Venezuelan bolívar | Bs. | VES |\n| Vietnamese đồng | ₫ | VND |\n| West African CFA franc | Fr | XOF |\n| Yemeni rial | ﷼ | YER |\n| Zambian kwacha | ZK | ZMW |\n| Zimbabwean dollar | $ | ZWL |\n\n\n
\n\n
\nRequest limits\n\n\nYou can perform up to 780 requests per minute for each Account. If you exceed this limit, you'll get a 429 Too Many Requests response for subsequent requests.\n\nWe recommend you handle 429 responses so your integration retries requests automatically.\n\n\n
\n\n\n", "version": "2.0.0", "contact": { "name": "InvoiceXpress API Support", "email": "support@invoicexpress.com" }, "x-logo": { "url": "../images/ix-logo.svg", "altText": "InvoiceXpress Logo" } }, "servers": [ { "url": "https://{account_name}.app.invoicexpress.com", "description": "Production Server", "variables": { "account_name": { "default": "your-account", "description": "Your account subdomain." } } } ], "tags": [ { "name": "Accounts", "description": "Create, update and get info about your account." }, { "name": "Invoices", "description": "Create invoices, invoice receipts, simplified invoices, vat moss invoices, credit notes & debit notes and send them to your clients." }, { "name": "Estimates", "description": "Create quotes, proformas or fees notes and send them to your clients." }, { "name": "Guides", "description": "Create shippings, transports & devolutions and send them to your clients." }, { "name": "Sequences", "description": "A Sequence is used to group invoices in a sequential order." }, { "name": "Taxes", "description": "A Tax is applied to invoice items when creating invoices." }, { "name": "SAF-T", "description": "Export the Standard Audit File for Tax (SAF-T PT) required by the Portuguese Tax Authority." }, { "name": "Clients", "description": "A Client is an entity you send invoices to." }, { "name": "Items", "description": "An Item is the product or service you invoice." }, { "name": "Treasury", "description": "Section dedicated to treasury movements." } ], "security": [ { "apiKeyAuth": [] } ], "paths": { "/api/accounts/create.json": { "post": { "summary": "Create Account", "operationId": "createAccount", "tags": [ "Accounts" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountCreateRequest" } } } }, "responses": { "201": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountCreateSuccess" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422CreateAccount" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://your-account.app.invoicexpress.com/api/accounts/create.json\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/api/accounts/create_already_user.json": { "post": { "summary": "Create for existing user", "operationId": "createAccountExisting", "tags": [ "Accounts" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountCreateRequest" } } } }, "responses": { "201": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountCreateSuccess" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422AlreadyUser" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://your-account.app.invoicexpress.com/api/accounts/create_already_user.json\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/api/accounts/{account-id}/get.json": { "get": { "summary": "Get Account", "operationId": "getAccount", "tags": [ "Accounts" ], "parameters": [ { "$ref": "#/components/parameters/AccountIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "responses": { "200": { "description": "SUCCESS.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountGetSuccess" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/api/accounts/1/get.json?api_key=YOUR_API_KEY\"" } ] } }, "/api/accounts/{account-id}/update.json": { "put": { "summary": "Update Account", "operationId": "updateAccount", "tags": [ "Accounts" ], "parameters": [ { "$ref": "#/components/parameters/AccountIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountUpdateRequest" } } } }, "responses": { "200": { "description": "SUCCESS" }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND" }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422UpdateAccount" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PUT \"https://your-account.app.invoicexpress.com/api/accounts/1/update.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/api/v3/accounts/at_communication.json": { "post": { "summary": "AT Communication", "operationId": "atCommunication", "tags": [ "Accounts" ], "parameters": [ { "$ref": "#/components/parameters/ApiKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AtCommunicationRequest" } } } }, "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AtCommunicationSuccess" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422AtCommunication" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://your-account.app.invoicexpress.com/api/v3/accounts/at_communication.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/invoices.json": { "get": { "summary": "List All", "operationId": "listInvoices", "tags": [ "Invoices" ], "description": "Returns a list of invoices.", "parameters": [ { "$ref": "#/components/parameters/ApiKeyParam" }, { "$ref": "#/components/parameters/ListInvoicesQueryParamns" } ], "responses": { "200": { "description": "SUCCESS \n\n#### Possible values for field atcud:\n\n* ABCD1234-1 (or similar) - Unique document identifier to the Tax Authority, when the sequence is registered.\n* N/D - The document's sequence is relevant for ATCUD but is not registered in the Tax Authority.\n* N/A - The document's sequence is not relevant for ATCUD and is not registered in the Tax Authority.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceListAllResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/invoices.json?api_key=YOUR_API_KEY&type[]=Invoice&status[]=sent&date[from]=01/01/2024&date[to]=31/12/2024&due_date[from]=01/01/2024&due_date[to]=31/12/2024&total_before_taxes[from]=0&total_before_taxes[to]=1000\"" } ] } }, "/{invoices-type}.json": { "post": { "summary": "Create Invoice", "operationId": "createInvoice", "tags": [ "Invoices" ], "description": "Creates a new invoice, simplified_invoice, invoice_receipt, credit_note or debit_note.\n\n### Idempotency\nSend a `proprietary_uid` (at the top level or inside the root object) to make the request safe to retry:\n* If a document with that `proprietary_uid` was already created, the API returns `201` with the original document instead of creating a new one.\n* If another request with the same `proprietary_uid` is still being saved, the API returns `422` with `This document is being saved by another request. Please try again.`\n\nEnglish text shown; the message follows the account language.\n\n\n\n### Creating new clients or items along with the documents\nThis method also allows to create a new client and/or new items in the same request with the following behavior:\n* If the client name does not exist, a new one is created.\n* If items do not exist with the given names, new ones will be created.\n* If item name already exists, the item is updated with the new values.\n\n### Taxes\nRegarding item taxes, if the tax name is not found, the default tax is applyed to that item. Portuguese accounts should also send the IVA exemption reason if the invoice contains exempt items (IVA 0%).\n\n> **Note:** Simplified Invoices are only available in Portugal.\n", "parameters": [ { "$ref": "#/components/parameters/ApiKeyParam" }, { "$ref": "#/components/parameters/DocumentTypeInvoiceParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceCreateRequest" } } } }, "responses": { "201": { "description": "SUCCESS \n\n#### Possible values for field atcud:\n\n* ABCD1234-1 (or similar) - Unique document identifier to the Tax Authority, when the sequence is registered.\n* N/D - The document's sequence is relevant for ATCUD but is not registered in the Tax Authority.\n* N/A - The document's sequence is not relevant for ATCUD and is not registered in the Tax Authority.\n\n#### Response wrapper key\n\nThe parent key shown in the example below as `invoice` is only an example — it always matches the singular of the requested `{invoices-type}` path parameter: `invoice` for `invoices`, `invoice_receipt` for `invoice_receipts`, `simplified_invoice` for `simplified_invoices`, `credit_note` for `credit_notes`, and `debit_note` for `debit_notes`. The nested object shape is identical in every case.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceGetResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422CreateInvoice" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://your-account.app.invoicexpress.com/invoices.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/{estimates-type}.json": { "post": { "summary": "Create Estimate", "operationId": "createEstimate", "tags": [ "Estimates" ], "description": "Creates a new quote, proforma or fees_note.", "parameters": [ { "$ref": "#/components/parameters/ApiKeyParam" }, { "$ref": "#/components/parameters/DocumentTypeEstimateParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateCreateRequest" } } } }, "responses": { "201": { "description": "SUCCESS \n\n#### Possible values for field atcud:\n\n* ABCD1234-1 (or similar) - Unique document identifier to the Tax Authority, when the sequence is registered.\n* N/D - The document's sequence is relevant for ATCUD but is not registered in the Tax Authority.\n* N/A - The document's sequence is not relevant for ATCUD and is not registered in the Tax Authority.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateGetResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422CreateInvoice" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://your-account.app.invoicexpress.com/quotes.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/{guides-type}.json": { "post": { "summary": "Create Guide", "operationId": "createGuide", "tags": [ "Guides" ], "description": "Creates a new shipping, transport or devolution.", "parameters": [ { "$ref": "#/components/parameters/ApiKeyParam" }, { "$ref": "#/components/parameters/DocumentTypeGuideParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideCreateRequest" } } } }, "responses": { "201": { "description": "SUCCESS \n\n#### Possible values for field atcud:\n\n* ABCD1234-1 (or similar) - Unique document identifier to the Tax Authority, when the sequence is registered.\n* N/D - The document's sequence is relevant for ATCUD but is not registered in the Tax Authority.\n* N/A - The document's sequence is not relevant for ATCUD and is not registered in the Tax Authority.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideGetResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422CreateInvoice" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://your-account.app.invoicexpress.com/shippings.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/{invoices-type}/{document-id}.json": { "get": { "summary": "Get Invoice", "operationId": "getInvoice", "tags": [ "Invoices" ], "parameters": [ { "$ref": "#/components/parameters/DocumentIdParam" }, { "$ref": "#/components/parameters/DocumentTypeInvoiceParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "responses": { "200": { "description": "SUCCESS \n\n#### Possible values for field atcud:\n\n* ABCD1234-1 (or similar) - Unique document identifier to the Tax Authority, when the sequence is registered.\n* N/D - The document's sequence is relevant for ATCUD but is not registered in the Tax Authority.\n* N/A - The document's sequence is not relevant for ATCUD and is not registered in the Tax Authority.\n\n#### Response wrapper key\n\nThe parent key shown in the example below as `invoice` is only an example — it always matches the singular of the requested `{invoices-type}` path parameter: `invoice` for `invoices`, `invoice_receipt` for `invoice_receipts`, `simplified_invoice` for `simplified_invoices`, `credit_note` for `credit_notes`, and `debit_note` for `debit_notes`. The nested object shape is identical in every case.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceGetResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Documents" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/invoices/1050.json?api_key=YOUR_API_KEY\"" } ] }, "put": { "summary": "Update Invoice", "operationId": "updateInvoice", "tags": [ "Invoices" ], "description": "Updates an existing draft invoice, simplified_invoice, invoice_receipt, credit_note or debit_note.\n\nOnly `items` is required. The items list is replaced by the one sent; the client and any other field that is not sent keep their current values.\n\n\n\n### Creating new clients or items along with the invoice\nThis method also allows to create a new client and/or new items in the same request with the following behavior:\n* If the client name does not exist, a new one is created.\n* If items do not exist with the given names, new ones will be created.\n* If item name already exists, the item is updated with the new values.\n\n### Taxes\nRegarding item taxes, if the tax name is not found, the default tax is applyed to that item. Portuguese accounts should also send the IVA exemption reason if the invoice contains exempt items (IVA 0%).\n\n> **Note:** Simplified Invoices are only available in Portugal.\n", "parameters": [ { "$ref": "#/components/parameters/DocumentTypeInvoiceParam" }, { "$ref": "#/components/parameters/DocumentIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceUpdateRequest" } } } }, "responses": { "200": { "description": "SUCCESS \n\n#### Possible values for field atcud:\n\n* ABCD1234-1 (or similar) - Unique document identifier to the Tax Authority, when the sequence is registered.\n* N/D - The document's sequence is relevant for ATCUD but is not registered in the Tax Authority.\n* N/A - The document's sequence is not relevant for ATCUD and is not registered in the Tax Authority.\n\n#### Response wrapper key\n\nThe parent key shown in the example below as `invoice` is only an example — it always matches the singular of the requested `{invoices-type}` path parameter: `invoice` for `invoices`, `invoice_receipt` for `invoice_receipts`, `simplified_invoice` for `simplified_invoices`, `credit_note` for `credit_notes`, and `debit_note` for `debit_notes`. The nested object shape is identical in every case.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceGetResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Documents" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422UpdateInvoices" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PUT \"https://your-account.app.invoicexpress.com/invoices/1050.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/{estimates-type}/{document-id}.json": { "get": { "summary": "Get Estimate", "operationId": "getEstimate", "tags": [ "Estimates" ], "parameters": [ { "$ref": "#/components/parameters/DocumentIdParam" }, { "$ref": "#/components/parameters/DocumentTypeEstimateParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "responses": { "200": { "description": "SUCCESS \n\n#### Possible values for field atcud:\n\n* ABCD1234-1 (or similar) - Unique document identifier to the Tax Authority, when the sequence is registered.\n* N/D - The document's sequence is relevant for ATCUD but is not registered in the Tax Authority.\n* N/A - The document's sequence is not relevant for ATCUD and is not registered in the Tax Authority.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateGetResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Documents" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/quotes/1050.json?api_key=YOUR_API_KEY\"" } ] }, "put": { "summary": "Update Estimate", "operationId": "updateEstimate", "tags": [ "Estimates" ], "description": "Updates a draft quote, proforma or fees_note.\n\nOnly `items` is required. The items list is replaced by the one sent; the client and any other field that is not sent keep their current values. A request without `items` fails with `422` `No items element provided`.\n", "parameters": [ { "$ref": "#/components/parameters/DocumentTypeEstimateParam" }, { "$ref": "#/components/parameters/DocumentIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateCreateRequest" } } } }, "responses": { "200": { "description": "SUCCESS \n\n#### Possible values for field atcud:\n\n* ABCD1234-1 (or similar) - Unique document identifier to the Tax Authority, when the sequence is registered.\n* N/D - The document's sequence is relevant for ATCUD but is not registered in the Tax Authority.\n* N/A - The document's sequence is not relevant for ATCUD and is not registered in the Tax Authority.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateGetResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Documents" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422UpdateInvoices" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PUT \"https://your-account.app.invoicexpress.com/quotes/1050.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/{guides-type}/{document-id}.json": { "get": { "summary": "Get Guide", "operationId": "getGuide", "tags": [ "Guides" ], "parameters": [ { "$ref": "#/components/parameters/DocumentIdParam" }, { "$ref": "#/components/parameters/DocumentTypeGuideParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "responses": { "200": { "description": "SUCCESS \n\n#### Possible values for field atcud:\n\n* ABCD1234-1 (or similar) - Unique document identifier to the Tax Authority, when the sequence is registered.\n* N/D - The document's sequence is relevant for ATCUD but is not registered in the Tax Authority.\n* N/A - The document's sequence is not relevant for ATCUD and is not registered in the Tax Authority.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideGetResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Documents" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/shippings/1050.json?api_key=YOUR_API_KEY\"" } ] }, "put": { "summary": "Update Guide", "operationId": "updateGuide", "tags": [ "Guides" ], "description": "Updates a draft shipping, transport or devolution.\n\nSend `items` and `loaded_at` (not in the past) and, on Portuguese accounts, `address_from` and `address_to`; otherwise the request fails with `422` (for example `No items element provided` or `Load date must be on or after `). The items list is replaced; the client and other fields not sent keep their current values, except that on non-Portuguese accounts the addresses are cleared.\n", "parameters": [ { "$ref": "#/components/parameters/DocumentTypeGuideParam" }, { "$ref": "#/components/parameters/DocumentIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideCreateRequest" } } } }, "responses": { "200": { "description": "SUCCESS \n\n#### Possible values for field atcud:\n\n* ABCD1234-1 (or similar) - Unique document identifier to the Tax Authority, when the sequence is registered.\n* N/D - The document's sequence is relevant for ATCUD but is not registered in the Tax Authority.\n* N/A - The document's sequence is not relevant for ATCUD and is not registered in the Tax Authority.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideGetResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Documents" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422UpdateInvoices" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PUT \"https://your-account.app.invoicexpress.com/shippings/1050.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/{invoices-type}/{document-id}/change-state.json": { "put": { "summary": "Change Invoice State", "operationId": "changeInvoiceState", "tags": [ "Invoices" ], "description": "Changes the state of invoice documents.\n\n| From | To | State on Request Body | Notes |\n| :--- | :--- | :--- | :--- |\n| draft | final | **finalized** | All documents except `invoice_receipt`. |\n| draft | settled | **finalized** | Only `invoice_receipt`. |\n| draft | deleted | **deleted** | All documents. |\n| final | canceled | **canceled** | All documents. Requires `message` (the cancellation reason). |\n| settled | canceled | **canceled** | Only `invoice_receipt`. Requires `message`. |\n| final | settled | **settled** | `invoice`, `simplified_invoice`, `credit_note` and `debit_note`. Not available for `invoice_receipt`. |\n| settled | final | **unsettled** | Only `credit_note` and `debit_note`. |\n\n> **Note:** An `invoice` or `simplified_invoice` settled with **settled** cannot be returned to final or canceled through the API.\n", "parameters": [ { "$ref": "#/components/parameters/DocumentTypeInvoiceParam" }, { "$ref": "#/components/parameters/DocumentIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeStateInvoiceRequest" } } } }, "responses": { "200": { "description": "SUCCESS \n\n#### Possible values for field atcud:\n\n* ABCD1234-1 (or similar) - Unique document identifier to the Tax Authority, when the sequence is registered.\n* N/D - The document's sequence is relevant for ATCUD but is not registered in the Tax Authority.\n* N/A - The document's sequence is not relevant for ATCUD and is not registered in the Tax Authority.\n\n#### Response wrapper key\n\nThe parent key shown in the example below as `invoice` is only an example — it always matches the singular of the requested `{invoices-type}` path parameter: `invoice` for `invoices`, `invoice_receipt` for `invoice_receipts`, `simplified_invoice` for `simplified_invoices`, `credit_note` for `credit_notes`, and `debit_note` for `debit_notes`. The nested object shape is identical in every case.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceGetResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Documents" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422ChangeState" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PUT \"https://your-account.app.invoicexpress.com/invoices/1050/change-state.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/{estimates-type}/{document-id}/change-state.json": { "put": { "summary": "Change Estimate State", "operationId": "changeEstimateState", "tags": [ "Estimates" ], "description": "Changes the state of estimate documents (quotes, proformas, fees_notes).\n\n| From | To | Event |\n| :--- | :--- | :--- |\n| Draft | final | `finalized` |\n| Draft | deleted | `deleted` |\n| final | Accepted | `accept` |\n| final | refused | `refuse` |\n| final | canceled | `canceled` |\n| Accepted | refused | `refuse` |\n| refused | Accepted | `accept` |\n| Accepted | canceled | `canceled` |\n| refused | canceled | `canceled` |\n", "parameters": [ { "$ref": "#/components/parameters/DocumentTypeEstimateParam" }, { "$ref": "#/components/parameters/DocumentIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeStateEstimateRequest" } } } }, "responses": { "200": { "description": "SUCCESS \n\n#### Possible values for field atcud:\n\n* ABCD1234-1 (or similar) - Unique document identifier to the Tax Authority, when the sequence is registered.\n* N/D - The document's sequence is relevant for ATCUD but is not registered in the Tax Authority.\n* N/A - The document's sequence is not relevant for ATCUD and is not registered in the Tax Authority.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateGetResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Documents" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422ChangeState" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PUT \"https://your-account.app.invoicexpress.com/quotes/1050/change-state.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/{guides-type}/{document-id}/change-state.json": { "put": { "summary": "Change Guide State", "operationId": "changeGuideState", "tags": [ "Guides" ], "description": "Changes the state of guide documents (shippings, transports, devolutions).\n\n| From | To | Event |\n| :--- | :--- | :--- |\n| draft | final | **finalized** |\n| draft | deleted | **deleted** |\n| final | canceled | **canceled** |\n", "parameters": [ { "$ref": "#/components/parameters/DocumentTypeGuideParam" }, { "$ref": "#/components/parameters/DocumentIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeStateGuideRequest" } } } }, "responses": { "200": { "description": "SUCCESS \n\n#### Possible values for field atcud:\n\n* ABCD1234-1 (or similar) - Unique document identifier to the Tax Authority, when the sequence is registered.\n* N/D - The document's sequence is relevant for ATCUD but is not registered in the Tax Authority.\n* N/A - The document's sequence is not relevant for ATCUD and is not registered in the Tax Authority.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideGetResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Documents" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422ChangeState" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PUT \"https://your-account.app.invoicexpress.com/shippings/1050/change-state.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/{invoices-type}/{document-id}/email-document.json": { "put": { "summary": "Send Invoice by Email", "operationId": "sendInvoiceEmail", "tags": [ "Invoices" ], "parameters": [ { "$ref": "#/components/parameters/DocumentTypeInvoiceParam" }, { "$ref": "#/components/parameters/DocumentIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDocumentRequest" } } } }, "responses": { "200": { "description": "SUCCESS" }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "403": { "description": "FORBIDDEN — the account's email service is disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/403SendEmail" } } } }, "404": { "description": "NOT FOUND" }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422SendEmail" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PUT \"https://your-account.app.invoicexpress.com/invoices/1050/email-document.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/{estimates-type}/{document-id}/email-document.json": { "put": { "summary": "Send Estimate by Email", "operationId": "sendEstimateEmail", "tags": [ "Estimates" ], "parameters": [ { "$ref": "#/components/parameters/DocumentTypeEstimateParam" }, { "$ref": "#/components/parameters/DocumentIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDocumentRequest" } } } }, "responses": { "200": { "description": "SUCCESS" }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "403": { "description": "FORBIDDEN — the account's email service is disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/403SendEmail" } } } }, "404": { "description": "NOT FOUND" }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422SendEmail" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PUT \"https://your-account.app.invoicexpress.com/quotes/1050/email-document.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/{guides-type}/{document-id}/email-document.json": { "put": { "summary": "Send Guide by Email", "operationId": "sendGuideEmail", "tags": [ "Guides" ], "parameters": [ { "$ref": "#/components/parameters/DocumentTypeGuideParam" }, { "$ref": "#/components/parameters/DocumentIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDocumentRequest" } } } }, "responses": { "200": { "description": "SUCCESS" }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "403": { "description": "FORBIDDEN — the account's email service is disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/403SendEmail" } } } }, "404": { "description": "NOT FOUND" }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422SendEmail" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PUT \"https://your-account.app.invoicexpress.com/shippings/1050/email-document.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/estimates.json": { "get": { "summary": "List All", "operationId": "listEstimates", "tags": [ "Estimates" ], "description": "Returns a list of estimates (Quotes, Proformas, Fees Notes).", "parameters": [ { "$ref": "#/components/parameters/ApiKeyParam" }, { "$ref": "#/components/parameters/ListEstimatesQueryParamns" } ], "responses": { "200": { "description": "SUCCESS \n\n#### Possible values for field atcud:\n\n* ABCD1234-1 (or similar) - Unique document identifier to the Tax Authority, when the sequence is registered.\n* N/D - The document's sequence is relevant for ATCUD but is not registered in the Tax Authority.\n* N/A - The document's sequence is not relevant for ATCUD and is not registered in the Tax Authority.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimatesListAll" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/estimates.json?api_key=YOUR_API_KEY&type[]=Quote&status[]=sent&valid_to[from]=01/01/2024&valid_to[to]=31/12/2024&date[from]=01/01/2024&date[to]=31/12/2024&total_before_taxes[from]=0&total_before_taxes[to]=1000\"" } ] } }, "/api/pdf/{document-id}.json": { "get": { "summary": "Generate PDF", "operationId": "generatePdf", "tags": [ "Invoices", "Estimates", "Guides" ], "parameters": [ { "$ref": "#/components/parameters/DocumentIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" }, { "name": "second_copy", "in": "query", "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfResponse" } } } }, "202": { "description": "ACCEPTED. The PDF is still being generated; repeat the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/202Pdf" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Documents" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/api/pdf/1050.json?api_key=YOUR_API_KEY&second_copy=false\"" } ] } }, "/api/qr_codes/{document-id}.json": { "get": { "summary": "Get QR Code", "operationId": "getQrCode", "tags": [ "Invoices", "Guides" ], "parameters": [ { "$ref": "#/components/parameters/DocumentIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrCodeResponse" } } } }, "202": { "description": "ACCEPTED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/202QRCode" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404QRCode" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422QRCode" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/api/qr_codes/1050.json?api_key=YOUR_API_KEY\"" } ] } }, "/document/{document-id}/related_documents.json": { "get": { "summary": "Related Documents", "operationId": "relatedDocs", "tags": [ "Invoices" ], "parameters": [ { "$ref": "#/components/parameters/DocumentIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "responses": { "200": { "description": "SUCCESS \n\n#### Possible values for field atcud:\n\n* ABCD1234-1 (or similar) - Unique document identifier to the Tax Authority, when the sequence is registered.\n* N/D - The document's sequence is relevant for ATCUD but is not registered in the Tax Authority.\n* N/A - The document's sequence is not relevant for ATCUD and is not registered in the Tax Authority.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/200RelatedDocuments" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Documents" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/document/1050/related_documents.json?api_key=YOUR_API_KEY\"" } ] } }, "/documents/{document-id}/partial_payments.json": { "post": { "summary": "Generate Payment", "operationId": "generatePayment", "tags": [ "Invoices" ], "parameters": [ { "$ref": "#/components/parameters/DocumentIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequest" } } } }, "responses": { "200": { "description": "SUCCESS \n\n#### Possible values for field atcud:\n\n* ABCD1234-1 (or similar) - Unique document identifier to the Tax Authority, when the sequence is registered.\n* N/D - The document's sequence is relevant for ATCUD but is not registered in the Tax Authority.\n* N/A - The document's sequence is not relevant for ATCUD and is not registered in the Tax Authority.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404GeneratePayment" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422GeneratePayment" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://your-account.app.invoicexpress.com/documents/1050/partial_payments.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/receipts/{receipt-id}/change-state.json": { "put": { "summary": "Cancel Payment", "operationId": "cancelReceipt", "tags": [ "Invoices" ], "parameters": [ { "name": "receipt-id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 } }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPaymentRequest" } } } }, "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Documents" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422CancelPayment" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PUT \"https://your-account.app.invoicexpress.com/receipts/42/change-state.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/guides.json": { "get": { "summary": "List All", "operationId": "listGuides", "tags": [ "Guides" ], "description": "Returns a list of guides (Shippings, Transports and Devolutions).", "parameters": [ { "$ref": "#/components/parameters/ApiKeyParam" }, { "$ref": "#/components/parameters/ListGuidesQueryParamns" } ], "responses": { "200": { "description": "SUCCESS \n\n#### Possible values for field atcud:\n\n* ABCD1234-1 (or similar) - Unique document identifier to the Tax Authority, when the sequence is registered.\n* N/D - The document's sequence is relevant for ATCUD but is not registered in the Tax Authority.\n* N/A - The document's sequence is not relevant for ATCUD and is not registered in the Tax Authority.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideListAll" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/guides.json?api_key=YOUR_API_KEY&type[]=Shipping&status[]=sent&loaded_at[from]=01/01/2024&loaded_at[to]=31/12/2024\"" } ] } }, "/api/export_saft.json": { "get": { "summary": "Export Saft", "operationId": "export_saft", "tags": [ "SAF-T" ], "parameters": [ { "$ref": "#/components/parameters/ApiKeyParam" }, { "$ref": "#/components/parameters/SaftExportQueryParams" } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Saft200Response" } } } }, "202": { "description": "ACCEPTED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Saft202Response" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Saft422Response" } } } }, "500": { "description": "FAILED TO GENERATE SAF-T", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Saft500Response" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/api/export_saft.json?api_key=YOUR_API_KEY&month=10&year=2017\"" } ] } }, "/sequences/{sequence_id}/register.json": { "put": { "summary": "Register Sequence", "operationId": "registerSequence", "tags": [ "Sequences" ], "description": "Registers a document sequence with the Tax Authority (AT).", "parameters": [ { "$ref": "#/components/parameters/SequenceIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "responses": { "200": { "description": "OK\n\n
\n\n**Possible values for fields `current__validation_code`:**\n\n| Value | Description |\n| :--- | :--- |\n| **ABCD1234** | Validation code for each sequence that is registered in the Tax Authority. |\n| **N/D** | The sequence is relevant for ATCUD but is not registered in the Tax Authority. |\n| **N/A** | The sequence is not relevant for ATCUD and is not registered in the Tax Authority. |\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sequence006Response" } } } }, "409": { "description": "CONFLICT\n\n**Available codes:**\n| Code | Description |\n| :--- | :--- |\n| **005** | All sequences are registered. |\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sequence005Response" } } } }, "422": { "description": "UNPROCESSABLE ENTITY\n\n**Available codes:**\n| Code | Description |\n| :--- | :--- |\n| **001** | Sequence name not allowed. |\n| **002** | Invalid Tax Authority credentials. |\n| **003** | Account fiscal ID doesn’t have open activity in Tax Authority. |\n| **004** | Account is not portuguese. |\n| **007** | Sequence already exists. |\n| **000** | Unknown error. |\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sequence001Response" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PUT \"https://your-account.app.invoicexpress.com/sequences/12345/register.json?api_key=YOUR_API_KEY\"" } ] } }, "/sequences.json": { "get": { "summary": "List All Sequences", "operationId": "listSequences", "tags": [ "Sequences" ], "description": "Returns all your sequences.", "parameters": [ { "$ref": "#/components/parameters/ApiKeyParam" } ], "responses": { "200": { "description": "Success.\n\n
\n\n**Possible values for fields `current__validation_code`:**\n\n| Value | Description |\n| :--- | :--- |\n| **ABCD1234** | Validation code for each sequence that is registered in the Tax Authority. |\n| **N/D** | The sequence is relevant for ATCUD but is not registered in the Tax Authority. |\n| **N/A** | The sequence is not relevant for ATCUD and is not registered in the Tax Authority. |\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/sequences.json?api_key=YOUR_API_KEY\"" } ] }, "post": { "summary": "Create Sequence", "operationId": "createSequence", "tags": [ "Sequences" ], "description": "Creates and registers a new sequence. \nFor portuguese accounts, it’s necessary to have AT credentials configured.\n", "parameters": [ { "$ref": "#/components/parameters/ApiKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceCreateRequest" } } } }, "responses": { "201": { "description": "SUCCESS. Created.\n\n
\n\n**Possible values for fields `current__validation_code`:**\n\n| Value | Description |\n| :--- | :--- |\n| **ABCD1234** | Validation code for each sequence that is registered in the Tax Authority. |\n| **N/D** | The sequence is relevant for ATCUD but is not registered in the Tax Authority. |\n| **N/A** | The sequence is not relevant for ATCUD and is not registered in the Tax Authority. |\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceGetResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "422": { "description": "UNPROCESSABLE ENTITY\n\n**Available codes:**\n| Code | Description |\n| :--- | :--- |\n| **001** | Sequence name not allowed. |\n| **002** | Sequence already exists. |\n| **003** | Invalid sequence. |\n| **004** | Invalid Tax Authority credentials. |\n| **005** | Account fiscal ID doesn’t have open activity in Tax Authority. |\n| **000** | Unknown error. |\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sequence001Response" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://your-account.app.invoicexpress.com/sequences.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/sequences/{sequence_id}.json": { "get": { "summary": "Get Sequence", "operationId": "getSequence", "tags": [ "Sequences" ], "description": "Returns a specific sequence.", "parameters": [ { "$ref": "#/components/parameters/SequenceIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "responses": { "200": { "description": "Success.\n\n
\n\n**Possible values for fields `current__validation_code`:**\n\n| Value | Description |\n| :--- | :--- |\n| **ABCD1234** | Validation code for each sequence that is registered in the Tax Authority. |\n| **N/D** | The sequence is relevant for ATCUD but is not registered in the Tax Authority. |\n| **N/A** | The sequence is not relevant for ATCUD and is not registered in the Tax Authority. |\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceGetResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/sequences/12345.json?api_key=YOUR_API_KEY\"" } ] } }, "/sequences/{sequence_id}/set_current.json": { "put": { "summary": "Set Sequence as Default", "operationId": "setSequenceDefault", "tags": [ "Sequences" ], "description": "Sets a specific sequence as the default.", "parameters": [ { "$ref": "#/components/parameters/SequenceIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "responses": { "200": { "description": "SUCCESS" }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND" }, "422": { "description": "UNPROCESSABLE ENTITY" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PUT \"https://your-account.app.invoicexpress.com/sequences/12345/set_current.json?api_key=YOUR_API_KEY\"" } ] } }, "/taxes.json": { "get": { "summary": "List All Taxes", "operationId": "listTaxes", "tags": [ "Taxes" ], "description": "Returns all your taxes.", "parameters": [ { "$ref": "#/components/parameters/ApiKeyParam" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxesResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/taxes.json?api_key=YOUR_API_KEY\"" } ] }, "post": { "summary": "Create Taxes", "operationId": "createTax", "tags": [ "Taxes" ], "description": "Creates a new tax.", "parameters": [ { "$ref": "#/components/parameters/ApiKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxesCreateRequest" } } } }, "responses": { "201": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxesGetResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422CreateTaxes" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://your-account.app.invoicexpress.com/taxes.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/taxes/{taxes_id}.json": { "get": { "summary": "Get Taxes", "operationId": "getTax", "tags": [ "Taxes" ], "description": "Returns a specific tax.", "parameters": [ { "$ref": "#/components/parameters/TaxesIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxesGetResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Taxes" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/taxes/12345.json?api_key=YOUR_API_KEY\"" } ] }, "put": { "summary": "Update Taxes", "operationId": "updateTax", "tags": [ "Taxes" ], "description": "Updates a tax.", "parameters": [ { "$ref": "#/components/parameters/TaxesIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxesUpdateRequest" } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Taxes" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422UpdateTaxes" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PUT \"https://your-account.app.invoicexpress.com/taxes/12345.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] }, "delete": { "summary": "Delete Tax", "operationId": "deleteTax", "tags": [ "Taxes" ], "description": "Deletes a tax.", "parameters": [ { "$ref": "#/components/parameters/TaxesIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "responses": { "200": { "description": "Success" }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Taxes" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE \"https://your-account.app.invoicexpress.com/taxes/12345.json?api_key=YOUR_API_KEY\"" } ] } }, "/clients.json": { "get": { "summary": "List All Clients", "operationId": "listClients", "tags": [ "Clients" ], "description": "Returns a list of all your clients.", "parameters": [ { "$ref": "#/components/parameters/ApiKeyParam" }, { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientsListAll" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/clients.json?api_key=YOUR_API_KEY&page=1&per_page=30\"" } ] }, "post": { "summary": "Create Client", "operationId": "createClient", "tags": [ "Clients" ], "description": "Creates a new client.", "parameters": [ { "$ref": "#/components/parameters/ApiKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRequest" } } } }, "responses": { "201": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientsGetResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422CreateClients" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://your-account.app.invoicexpress.com/clients.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/clients/{client_id}.json": { "get": { "summary": "Get Client", "operationId": "getClient", "tags": [ "Clients" ], "description": "Returns a specific client.", "parameters": [ { "$ref": "#/components/parameters/ClientsIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "responses": { "200": { "description": "SUCCESS.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientsGetResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Client" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/clients/12345.json?api_key=YOUR_API_KEY\"" } ] }, "put": { "summary": "Update Client", "operationId": "updateClient", "tags": [ "Clients" ], "description": "Updates a client.", "parameters": [ { "$ref": "#/components/parameters/ClientsIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRequest" } } } }, "responses": { "200": { "description": "SUCCESS" }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Client" } } } }, "422": { "description": "UNPROCESSABLE ENTITY" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PUT \"https://your-account.app.invoicexpress.com/clients/12345.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/clients/find-by-name.json": { "get": { "summary": "Find Client by Name", "operationId": "findClientByName", "tags": [ "Clients" ], "description": "Returns a specific client.", "parameters": [ { "$ref": "#/components/parameters/FindByName" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "responses": { "200": { "description": "SUCCESS.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientsGetResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/clients/find-by-name.json?api_key=YOUR_API_KEY&client_name=foo\"" } ] } }, "/clients/find-by-code.json": { "get": { "summary": "Find Client by Code", "operationId": "findClientByCode", "tags": [ "Clients" ], "description": "Returns a specific client.", "parameters": [ { "$ref": "#/components/parameters/FindByCode" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "responses": { "200": { "description": "SUCCESS.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientsGetResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/clients/find-by-code.json?api_key=YOUR_API_KEY&client_code=foo\"" } ] } }, "/clients/{client_id}/invoices.json": { "post": { "summary": "List Client Invoices", "operationId": "listClientInvoices", "tags": [ "Clients" ], "description": "This method allows you to obtain the invoices for a specific client. You can filter the results by document status, type and if it’s archived or not.", "parameters": [ { "name": "client_id", "in": "path", "required": true, "description": "Filter invoices for this client.", "schema": { "type": "integer", "example": 42 } }, { "$ref": "#/components/parameters/ApiKeyParam" }, { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientsInvoiceFilterRequest" } } } }, "responses": { "200": { "description": "SUCCESS. Returns the client's invoices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientsInvoicesResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://your-account.app.invoicexpress.com/clients/42/invoices.json?api_key=YOUR_API_KEY&page=1&per_page=30\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/items.json": { "get": { "summary": "List All Items", "operationId": "listItems", "tags": [ "Items" ], "description": "Returns a list of all your items.", "parameters": [ { "$ref": "#/components/parameters/ApiKeyParam" }, { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemsListAll" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/items.json?api_key=YOUR_API_KEY&page=1&per_page=30\"" } ] }, "post": { "summary": "Create Item", "operationId": "createItem", "tags": [ "Items" ], "description": "Creates a new item.", "parameters": [ { "$ref": "#/components/parameters/ApiKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemRequest" } } } }, "responses": { "201": { "description": "SUCCESS. Returns the created item.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemsGetResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422CreateItems" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://your-account.app.invoicexpress.com/items.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/items/{item_id}.json": { "get": { "summary": "Get Item", "operationId": "getItem", "tags": [ "Items" ], "description": "Returns a specific item.", "parameters": [ { "$ref": "#/components/parameters/ItemsIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemsGetResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Items" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/items/12345.json?api_key=YOUR_API_KEY\"" } ] }, "put": { "summary": "Update Item", "operationId": "updateItem", "tags": [ "Items" ], "description": "Updates an item.", "parameters": [ { "$ref": "#/components/parameters/ItemsIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemRequest" } } } }, "responses": { "200": { "description": "SUCCESS" }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Items" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422UpdateItems" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PUT \"https://your-account.app.invoicexpress.com/items/12345.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] }, "delete": { "summary": "Delete Item", "operationId": "deleteItem", "tags": [ "Items" ], "description": "Deletes an item.", "parameters": [ { "$ref": "#/components/parameters/ItemsIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "responses": { "200": { "description": "SUCCESS" }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Items" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE \"https://your-account.app.invoicexpress.com/items/12345.json?api_key=YOUR_API_KEY\"" } ] } }, "/api/v3/clients/{client_id}/balance.json": { "get": { "summary": "Get Client Balance", "operationId": "getClientBalance", "tags": [ "Treasury" ], "description": "Returns the balance of a specific client.", "parameters": [ { "$ref": "#/components/parameters/ClientsIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientBalanceResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Clients" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/api/v3/clients/12345/balance.json?api_key=YOUR_API_KEY\"" } ] } }, "/api/v3/clients/{client_id}/initial_balance.json": { "put": { "summary": "Update Initial Balance", "operationId": "updateClientInitialBalance", "tags": [ "Treasury" ], "description": "Updates the initial balance of a specific client.", "parameters": [ { "$ref": "#/components/parameters/ClientsIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialBalanceRequest" } } } }, "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialBalanceResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Clients" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422InitialBalance" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PUT \"https://your-account.app.invoicexpress.com/api/v3/clients/12345/initial_balance.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/api/v3/clients/{client_id}/regularization.json": { "get": { "summary": "Get Client Regularization", "operationId": "getClientRegularizations", "tags": [ "Treasury" ], "description": "Returns a list of all your client’s regularization.", "parameters": [ { "$ref": "#/components/parameters/ClientsIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegularizationListResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Clients" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://your-account.app.invoicexpress.com/api/v3/clients/12345/regularization.json?api_key=YOUR_API_KEY\"" } ] }, "post": { "summary": "Create Regularization", "operationId": "createClientRegularization", "tags": [ "Treasury" ], "description": "Creates a new client’s regularization.", "parameters": [ { "$ref": "#/components/parameters/ClientsIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegularizationRequest" } } } }, "responses": { "201": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegularizationCreateResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Clients" } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422CreateRegularization" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://your-account.app.invoicexpress.com/api/v3/clients/12345/regularization.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/api/v3/clients/{client_id}/regularization/{id}.json": { "delete": { "summary": "Delete Regularization", "operationId": "deleteClientRegularization", "tags": [ "Treasury" ], "description": "Deletes a client’s regularization.", "parameters": [ { "$ref": "#/components/parameters/ClientsIdParam" }, { "$ref": "#/components/parameters/TreasuryIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "responses": { "204": { "description": "SUCCESS. No content." }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Regularization" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE \"https://your-account.app.invoicexpress.com/api/v3/clients/12345/regularization/1.json?api_key=YOUR_API_KEY\"" } ] } }, "/api/v3/clients/{client_id}/treasury_movements.json": { "post": { "summary": "Create Treasury Movement", "operationId": "createClientTreasuryMovement", "tags": [ "Treasury" ], "description": "Creates a new client’s treasury movement.\n\n* **Payment**: the value must be less than or equal to the client's outstanding balance. The amount is applied to the client's open documents (status sent or second_copy), and a receipt is issued for each. The receipt PDFs are emailed to the account owner.\n* **Reimbursement**: the value must be less than or equal to the amount already settled.\n* A `date` string that cannot be parsed (for example `31/02/2023`) is replaced by today's date.\n\nSend an `Idempotency-Key` header to make the request safe to retry.\n", "parameters": [ { "$ref": "#/components/parameters/ClientsIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for this request. A retry with the same key does not create a second movement. The same key with a different payload is rejected with 422, unless the first attempt was rejected with a 4xx.", "schema": { "type": "string", "example": "3f1c2a9e-movement-1" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryMovementRequest" } } } }, "responses": { "201": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryMovementResponse" } } } }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Clients" } } } }, "409": { "description": "CONFLICT", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": [ { "error": "A request with this Idempotency-Key is still being processed. Wait for it to finish before retrying." } ] } } } } } }, "422": { "description": "UNPROCESSABLE ENTITY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422Treasury" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://your-account.app.invoicexpress.com/api/v3/clients/12345/treasury_movements.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'" } ] } }, "/api/v3/clients/{client_id}/treasury_movements/{id}.json": { "delete": { "summary": "Delete Treasury Movement", "operationId": "deleteClientTreasuryMovement", "tags": [ "Treasury" ], "description": "Deletes a client’s treasury movement.", "parameters": [ { "$ref": "#/components/parameters/ClientsIdParam" }, { "$ref": "#/components/parameters/TreasuryIdParam" }, { "$ref": "#/components/parameters/ApiKeyParam" } ], "responses": { "204": { "description": "SUCCESS" }, "401": { "description": "ACCESS DENIED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "404": { "description": "NOT FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404TreasuryMovement" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE \"https://your-account.app.invoicexpress.com/api/v3/clients/12345/treasury_movements/1.json?api_key=YOUR_API_KEY\"" } ] } } }, "components": { "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "query", "name": "api_key" } }, "parameters": { "ApiKeyParam": { "name": "api_key", "in": "query", "required": true, "schema": { "type": "string", "example": "YOUR_API_KEY" }, "description": "Your API Key." }, "DocumentTypeInvoiceParam": { "name": "invoices-type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "invoices", "invoice_receipts", "simplified_invoices", "credit_notes", "debit_notes" ] }, "description": "The type of the invoice document." }, "DocumentTypeEstimateParam": { "name": "estimates-type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "quotes", "proformas", "fees_notes" ] }, "description": "The type of the estimate document." }, "DocumentTypeGuideParam": { "name": "guides-type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "shippings", "transports", "devolutions" ] }, "description": "The type of the guide document." }, "DocumentIdParam": { "name": "document-id", "in": "path", "required": true, "schema": { "type": "integer", "example": 1050 }, "description": "The ID of the document." }, "AccountIdParam": { "name": "account-id", "in": "path", "required": true, "schema": { "type": "integer", "example": 1 } }, "ListInvoicesQueryParamns": { "name": "Query Parameters", "in": "query", "style": "form", "explode": true, "schema": { "$ref": "#/components/schemas/QueryParamns" }, "description": "Click to expand options." }, "ListEstimatesQueryParamns": { "name": "Query Parameters", "in": "query", "style": "form", "explode": true, "schema": { "$ref": "#/components/schemas/EstimateFilters" }, "description": "Click to expand options." }, "ListGuidesQueryParamns": { "name": "Query Parameters", "in": "query", "style": "form", "explode": true, "schema": { "$ref": "#/components/schemas/GuideQueryParamns" }, "description": "Click to expand options." }, "SaftExportQueryParams": { "name": "Saft Params", "in": "query", "style": "form", "explode": true, "required": true, "schema": { "$ref": "#/components/schemas/SaftExportParams" }, "description": "Click to expand options." }, "SequenceIdParam": { "name": "sequence_id", "in": "path", "required": true, "description": "ID of the sequence.", "schema": { "type": "string", "example": "12345" } }, "TaxesIdParam": { "name": "taxes_id", "in": "path", "required": true, "description": "ID of the tax.", "schema": { "type": "string", "example": "12345" } }, "ClientsIdParam": { "name": "client_id", "in": "path", "required": true, "description": "ID of the client.", "schema": { "type": "string", "example": "12345" } }, "PageParam": { "name": "page", "in": "query", "required": false, "description": "You can ask for a specific page of results. Defaults to 1.", "schema": { "type": "integer", "example": 1 } }, "PerPageParam": { "name": "per_page", "in": "query", "required": false, "description": "You can specify how many results you want to fetch. Defaults to 10 or value defined in account settings (10, 20 or 30).", "schema": { "type": "integer", "example": 30 } }, "FindByName": { "name": "client_name", "in": "query", "required": true, "description": "The client name you want to search. Warning: partial search is not supported.", "schema": { "type": "string", "example": "foo" } }, "FindByCode": { "name": "client_code", "in": "query", "required": true, "description": "The client code you want to search.", "schema": { "type": "string", "example": "foo" } }, "ItemsIdParam": { "name": "item_id", "in": "path", "required": true, "description": "ID of the item.", "schema": { "type": "string", "example": "12345" } }, "TreasuryIdParam": { "name": "id", "in": "path", "required": true, "description": "The ID of the regularization you want to delete.", "schema": { "type": "integer", "example": 1 } } }, "schemas": { "401": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string", "example": "Authentication Error" } } } } } }, "AccountCreateRequest": { "type": "object", "required": [ "account" ], "properties": { "account": { "type": "object", "required": [ "organization_name", "email", "password", "password_confirmation", "terms" ], "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "organization_name": { "type": "string", "example": "My Company", "maxLength": 100, "description": "Values longer than 100 characters are rejected with HTTP 422." }, "phone": { "type": "string", "example": "912345678", "maxLength": 255 }, "email": { "type": "string", "example": "john.doe@example.com", "maxLength": 255 }, "password": { "type": "string", "example": "secret123" }, "password_confirmation": { "type": "string", "example": "secret123" }, "fiscal_id": { "type": "string", "example": "500100200", "maxLength": 255 }, "address": { "type": "string", "example": "Rua Augusta, 1", "description": "Optional. Can be completed later." }, "postal_code": { "type": "string", "example": "1100-048", "description": "Optional. Can be completed later." }, "city": { "type": "string", "example": "Lisboa", "description": "Optional. Can be completed later." }, "tax_country": { "type": "string", "enum": [ "1", "2", "3" ], "example": "1" }, "language": { "type": "string", "enum": [ "pt", "en", "es" ], "example": "pt" }, "terms": { "type": "string", "enum": [ "1", "0" ], "example": "1" }, "marketing": { "type": "string", "enum": [ "1", "0" ], "example": "0" } } } } }, "AccountCreateSuccess": { "type": "object", "properties": { "account": { "type": "object", "properties": { "id": { "type": "string", "example": "12345" }, "name": { "type": "string", "example": "mycompany", "maxLength": 20, "minLength": 3, "description": "Account subdomain (slug) used in the account URL — not the display name. The display name is `organization_name`." }, "url": { "type": "string", "example": "https://mycompany.app.invoicexpress.com" }, "api_key": { "type": "string", "example": "abc123xyz456" }, "state": { "type": "string", "example": "active", "maxLength": 255 } } } } }, "AccountGetSuccess": { "type": "object", "properties": { "account": { "type": "object", "properties": { "organization_name": { "type": "string", "example": "My Company", "maxLength": 100, "description": "Values longer than 100 characters are rejected with HTTP 422." }, "fiscal_id": { "type": "string", "example": "500100200", "maxLength": 255 }, "email": { "type": [ "string", "null" ], "example": "john.doe@example.com", "maxLength": 255 }, "state": { "type": "string", "example": "active", "maxLength": 255 }, "at_configured": { "type": "boolean", "example": true }, "trial": { "type": "boolean", "example": true } } } } }, "AccountUpdateRequest": { "type": "object", "required": [ "account" ], "properties": { "account": { "type": "object", "required": [ "organization_name", "email", "password", "terms" ], "properties": { "first_name": { "type": "string", "example": "My New Company Name" }, "last_name": { "type": "string", "example": "My New Company Name" }, "organization_name": { "type": "string", "example": "My New Company Name", "maxLength": 100, "description": "Values longer than 100 characters are rejected with HTTP 422." }, "phone": { "type": "string", "example": "210000000", "maxLength": 255 }, "email": { "type": "string", "example": "billing@company.com", "maxLength": 255 }, "password": { "type": "string", "example": "secret123" }, "fiscal_id": { "type": "string", "example": "500100200", "maxLength": 255, "description": "Cannot be changed" }, "address": { "type": "string", "example": "Main Street, 123", "maxLength": 210, "description": "Values longer than 210 characters are rejected with HTTP 422." }, "city": { "type": "string", "example": "Lisbon", "maxLength": 50, "description": "Values longer than 50 characters are rejected with HTTP 422." }, "postal_code": { "type": "string", "example": "1000-001", "maxLength": 255 }, "website": { "type": "string", "example": "www.company.com", "maxLength": 255 }, "fax": { "type": "string", "example": "210000001", "maxLength": 255 }, "terms": { "type": "string", "enum": [ "1", "0" ], "example": "1" }, "credentials": { "$ref": "#/components/schemas/Credentials" } } } } }, "Credentials": { "type": "object", "description": "AT Credentials.", "required": [ "username", "password" ], "properties": { "username": { "type": "string", "example": "500100200/1" }, "password": { "type": "string", "example": "password" }, "type": { "type": "string", "enum": [ "AT" ], "default": "AT" }, "context": { "type": "string", "enum": [ "Sequences" ], "default": "Sequences" } } }, "AtCommunicationRequest": { "type": "object", "required": [ "at_communication" ], "properties": { "at_communication": { "type": "object", "required": [ "at_subuser", "at_password", "communication_type" ], "properties": { "at_subuser": { "type": "string", "example": "500100200/1", "maxLength": 255 }, "at_password": { "type": "string", "example": "password", "maxLength": 255 }, "communication_type": { "type": "string", "enum": [ "auto", "manual", "guides", "portal_at" ], "example": "auto" } } } } }, "AtCommunicationSuccess": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } }, "InvoiceCreateRequest": { "type": "object", "description": "Document details.", "required": [ "invoice" ], "properties": { "invoice": { "allOf": [ { "$ref": "#/components/schemas/CreateBody" }, { "required": [ "date", "items" ] } ] }, "proprietary_uid": { "type": "string", "example": "uuid-123", "description": "Idempotency key. Can also be sent inside the root object." } } }, "InvoiceUpdateRequest": { "type": "object", "description": "Document details. Only `items` is required. The items list is replaced by the one sent; the client and other fields that are not sent keep their current values.", "required": [ "invoice" ], "properties": { "invoice": { "allOf": [ { "$ref": "#/components/schemas/CreateBody" }, { "required": [ "items" ] } ] } } }, "ChangeStateInvoiceRequest": { "type": "object", "required": [ "invoice" ], "properties": { "invoice": { "type": "object", "required": [ "state" ], "properties": { "state": { "type": "string", "enum": [ "finalized", "deleted", "canceled", "settled", "unsettled" ], "example": "finalized" }, "message": { "type": "string", "example": "Wrong value", "description": "Cancellation reason. Required when `state` is `canceled`, otherwise the request fails with 422 `The cancellation reason is a required field`. No enforced character limit. English text shown; the message follows the account language." } } } } }, "EmailDocumentRequest": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "object", "required": [ "client" ], "properties": { "client": { "type": "object", "required": [ "email", "save" ], "properties": { "email": { "type": "string", "example": "dest@mail.com" }, "save": { "type": "string", "enum": [ "0", "1" ], "example": "1" } } }, "subject": { "type": "string", "example": "Invoice" }, "body": { "type": "string", "example": "Attached." }, "cc": { "type": "string", "example": "cc@mail.com" }, "bcc": { "type": "string", "example": "bcc@mail.com" }, "logo": { "type": "string", "enum": [ "0", "1" ], "example": "1" } } } } }, "PaymentRequest": { "type": "object", "required": [ "partial_payment" ], "properties": { "partial_payment": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number", "example": 10 }, "payment_mechanism": { "type": "string", "enum": [ "TB", "MB", "CC" ], "example": "TB" }, "note": { "type": "string", "example": "Transfer", "description": "Stored in full on the receipt (observations). The copy on the client's treasury movement is truncated to 255 characters." }, "serie": { "type": "string" }, "payment_date": { "type": "string", "example": "22/11/2025" } } } } }, "CancelPaymentRequest": { "type": "object", "required": [ "receipt" ], "properties": { "receipt": { "type": "object", "required": [ "state", "message" ], "properties": { "state": { "type": "string", "enum": [ "canceled" ], "example": "canceled" }, "message": { "type": "string", "example": "Error" } } } } }, "ChangeStateEstimateRequest": { "type": "object", "description": "Root key must match the singular of the requested `{estimates-type}`: `quote` for `quotes`, `proforma` for `proformas`, `fees_note` for `fees_notes`. `quote` is shown as an example.", "required": [ "quote" ], "properties": { "quote": { "type": "object", "required": [ "state" ], "properties": { "state": { "type": "string", "enum": [ "finalized", "canceled", "deleted", "accept", "refuse" ], "example": "finalized" }, "message": { "type": "string", "example": "Wrong value", "description": "Cancellation message. No enforced character limit (text column)." } } } } }, "EstimatesItemRequest": { "type": "object", "description": "Line Item.", "required": [ "name", "unit_price", "quantity" ], "properties": { "name": { "type": "string", "example": "Consulting", "maxLength": 60, "description": "Maximum 60 characters. V3 rejects a longer name with HTTP 422; V2 accepts the request and silently truncates the stored value to 60 characters." }, "description": { "type": "string", "example": "IT Services", "maxLength": 200, "description": "Maximum 200 characters and 20 lines. V3 rejects a longer description with HTTP 422; V2 accepts the request and silently truncates the stored value to 200 characters." }, "unit_price": { "type": "number", "example": 50 }, "quantity": { "type": "number", "example": 2 }, "unit": { "type": "string", "example": "hour", "description": "One of a fixed set of supported unit values." }, "discount": { "type": "number", "example": 0 }, "tax": { "$ref": "#/components/schemas/EstimatesTaxRequest" } } }, "EstimatesTaxRequest": { "type": "object", "properties": { "name": { "type": "string", "example": "IVA23", "maxLength": 255, "description": "Defaults to 255 characters at the database level." } } }, "EstimateCreateRequest": { "type": "object", "description": "Root key must match the singular of the requested `{estimates-type}`: `quote` for `quotes`, `proforma` for `proformas`, `fees_note` for `fees_notes`. `quote` is shown as an example.", "required": [ "quote" ], "properties": { "quote": { "type": "object", "required": [ "date", "items" ], "properties": { "date": { "type": "string", "example": "22/11/2025", "description": "dd/mm/yyyy" }, "due_date": { "type": "string", "example": "22/12/2025", "description": "dd/mm/yyyy. Defaults to `date` when omitted." }, "reference": { "type": "string", "example": "PO-999", "maxLength": 255 }, "observations": { "type": "string", "example": "Services rendered", "description": "No enforced character limit (text column)." }, "retention": { "type": "string", "example": "0" }, "tax_exemption": { "type": "string", "example": "M00" }, "sequence_id": { "type": "string", "example": "123456" }, "manual_sequence_number": { "type": "string", "maxLength": 255, "description": "255-character limit is the database column default, not an explicit business rule." }, "client": { "description": "Optional. When omitted, the document is issued to the generic `Consumidor Final` client.", "allOf": [ { "$ref": "#/components/schemas/DocumentClientRequest" } ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/EstimatesItemRequest" } }, "mb_reference": { "type": "string", "enum": [ "0", "1" ], "example": "1" }, "auto_add_related_document": { "type": "string", "example": "0" }, "tax_exemption_reason": { "type": "string", "example": "M00", "maxLength": 210, "description": "Validated at 210 characters by the document model, below the 255-character database column limit." } } } } }, "GuideGetResponse": { "type": "object", "properties": { "shipping": { "type": "object", "description": "Wrapper key matches the singular of the requested guide type — `shipping`, `transport` or `devolution`. Shown here as \"shipping\".", "properties": { "id": { "type": "integer", "example": 541797 }, "status": { "type": "string", "example": "final" }, "archived": { "type": "boolean", "example": false }, "type": { "type": "string", "example": "Shipping" }, "sequence_number": { "type": "string", "example": "1/D" }, "inverted_sequence_number": { "type": "string", "example": "D/1" }, "atcud": { "type": "string", "example": "ABCD1234-1" }, "date": { "type": "string", "example": "13/07/2017" }, "due_date": { "type": "string", "description": "dd/mm/yyyy", "example": "27/07/2026" }, "reference": { "type": [ "string", "null" ], "example": null, "maxLength": 255 }, "observations": { "type": [ "string", "null" ], "example": null, "description": "No enforced character limit (text column)." }, "retention": { "type": [ "string", "null" ], "example": null }, "loaded_at": { "type": "string", "description": "dd/mm/yyyy HH:mm:ss. Note the list endpoint returns this same field as date-only (dd/mm/yyyy).", "example": "27/07/2026 23:00:00" }, "license_plate": { "type": [ "string", "null" ], "example": "11-AA-22", "maxLength": 255, "description": "255-character limit is the database column default, not an explicit business rule." }, "permalink": { "type": "string", "example": "https://web.invoicexpress.com/documents/541797d75bbee48911934cbd4a4294946a324295f52b08" }, "saft_hash": { "type": "string", "example": "vaDf", "description": "No enforced character limit (text column)." }, "sum": { "type": "number", "example": 1 }, "discount": { "type": "number", "example": 0 }, "before_taxes": { "type": "number", "example": 1 }, "taxes": { "type": "number", "example": 0.07 }, "total": { "type": "number", "example": 1.07 }, "currency": { "type": "string", "example": "Euro" }, "address_from": { "type": "object", "properties": { "country": { "type": "string", "example": "Portugal", "maxLength": 255, "description": "Not stored on the address itself — resolved through a tax-location name lookup, falling back to Portugal." }, "postal_code": { "type": "string", "example": "1050-083", "maxLength": 255, "description": "255-character limit is the database column default on the Address model, not an explicit business rule." }, "detail": { "type": "string", "example": "Avenida Duque D'Avila, 46 - 3ºA", "maxLength": 255, "description": "255-character limit is the database column default on the Address model, not an explicit business rule. Note the API re-inserts line breaks roughly every 35 characters before storing, so an input close to 255 characters can overflow the column — keep well under the limit." }, "city": { "type": "string", "example": "Lisboa", "maxLength": 255, "description": "255-character limit is the database column default on the Address model, not an explicit business rule." } } }, "address_to": { "type": "object", "properties": { "country": { "type": "string", "example": "Portugal", "maxLength": 255, "description": "Not stored on the address itself — resolved through a tax-location name lookup, falling back to Portugal." }, "postal_code": { "type": "string", "example": "4000-327", "maxLength": 255, "description": "255-character limit is the database column default on the Address model, not an explicit business rule." }, "detail": { "type": "string", "example": "Avenida dos Aliados", "maxLength": 255, "description": "255-character limit is the database column default on the Address model, not an explicit business rule. Note the API re-inserts line breaks roughly every 35 characters before storing, so an input close to 255 characters can overflow the column — keep well under the limit." }, "city": { "type": "string", "example": "Porto", "maxLength": 255, "description": "255-character limit is the database column default on the Address model, not an explicit business rule." } } }, "client": { "type": "object", "properties": { "id": { "type": "integer", "example": 1310176 }, "name": { "type": "string", "example": "John", "maxLength": 100 }, "country": { "type": "string", "example": "Portugal", "maxLength": 255, "description": "255-character limit is the database column default, not an explicit business rule." } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "iPhone", "maxLength": 60, "description": "Maximum 60 characters. V3 rejects a longer name with HTTP 422; V2 accepts the request and silently truncates the stored value to 60 characters." }, "description": { "type": [ "string", "null" ], "example": null, "maxLength": 200, "description": "Maximum 200 characters and 20 lines. V3 rejects a longer description with HTTP 422; V2 accepts the request and silently truncates the stored value to 200 characters." }, "unit_price": { "type": "string", "example": "1.0" }, "unit": { "type": [ "string", "null" ], "example": "service", "description": "Restricted to a fixed set of unit values rather than length-limited free text." }, "quantity": { "type": "string", "example": "1.0" }, "tax": { "type": "object", "properties": { "id": { "type": "integer", "example": 31597 }, "name": { "type": "string", "example": "IVA7" }, "value": { "type": "number", "example": 7 } } }, "discount": { "type": "number", "example": 0 }, "subtotal": { "type": "number", "example": 1 }, "tax_amount": { "type": "number", "example": 0.07 }, "discount_amount": { "type": "number", "example": 0 }, "total": { "type": "number", "example": 1.07 } } } }, "sequence_id": { "type": [ "integer", "null" ], "example": 12345 }, "tax_exemption": { "type": "string", "example": "M01" }, "at_doc_code_id": { "type": [ "string", "null" ], "example": "999", "maxLength": 255, "readOnly": true, "description": "Read-only. Written only by the AT gateway and never accepted on input. The 255-character limit is the database column default, not an explicit business rule." } } } } }, "ChangeStateGuideRequest": { "type": "object", "description": "Root key must match the singular of the requested `{guides-type}`: `shipping` for `shippings`, `transport` for `transports`, `devolution` for `devolutions`. `shipping` is shown as an example.", "required": [ "shipping" ], "properties": { "shipping": { "type": "object", "required": [ "state" ], "properties": { "state": { "type": "string", "enum": [ "finalized", "canceled", "deleted" ], "example": "finalized" }, "message": { "type": "string", "example": "Wrong value", "description": "No enforced character limit (text column, stored as cancel_message)." } } } } }, "GuideListAllResponse": { "$ref": "#/components/schemas/GuideListAll" }, "GuideCreateRequest": { "type": "object", "description": "Root key must match the singular of the requested `{guides-type}`: `shipping` for `shippings`, `transport` for `transports`, `devolution` for `devolutions`. `shipping` is shown as an example.", "required": [ "shipping" ], "properties": { "shipping": { "type": "object", "description": "`address_from` and `address_to` (each with `detail`, `city`, `postal_code` and `country`) are required only on Portuguese accounts; otherwise the request fails with 422 `No address_from element provided` / `No address_to element provided`.", "required": [ "date", "loaded_at", "items" ], "properties": { "date": { "type": "string", "description": "dd/mm/yyyy", "example": "03/12/2017" }, "due_date": { "type": "string", "description": "dd/mm/yyyy. Defaults to `date` when omitted.", "example": "03/12/2017" }, "loaded_at": { "type": "string", "description": "dd/mm/yyyy HH:mm:ss. Must not be in the past, otherwise the request fails with 422 `Load date must be on or after `.", "example": "02/12/2030 19:00:00" }, "license_plate": { "type": "string", "example": "11-AA-22", "maxLength": 255, "description": "255-character limit is the database column default, not an explicit business rule." }, "address_from": { "type": "object", "required": [ "detail", "city", "postal_code", "country" ], "properties": { "detail": { "type": "string", "example": "Rua 5", "maxLength": 255, "description": "255-character limit is the database column default on the Address model, not an explicit business rule. Note the API re-inserts line breaks roughly every 35 characters before storing, so an input close to 255 characters can overflow the column — keep well under the limit." }, "city": { "type": "string", "example": "Lisboa", "maxLength": 255, "description": "255-character limit is the database column default on the Address model, not an explicit business rule." }, "postal_code": { "type": "string", "example": "1000-555", "maxLength": 255, "description": "255-character limit is the database column default on the Address model, not an explicit business rule." }, "country": { "type": "string", "example": "Portugal", "maxLength": 255, "description": "Not stored on the address itself — resolved through a tax-location name lookup, falling back to Portugal." } } }, "address_to": { "type": "object", "required": [ "detail", "city", "postal_code", "country" ], "properties": { "detail": { "type": "string", "example": "Avenida 10", "maxLength": 255, "description": "255-character limit is the database column default on the Address model, not an explicit business rule. Note the API re-inserts line breaks roughly every 35 characters before storing, so an input close to 255 characters can overflow the column — keep well under the limit." }, "city": { "type": "string", "example": "Porto", "maxLength": 255, "description": "255-character limit is the database column default on the Address model, not an explicit business rule." }, "postal_code": { "type": "string", "example": "2000-555", "maxLength": 255, "description": "255-character limit is the database column default on the Address model, not an explicit business rule." }, "country": { "type": "string", "example": "Portugal", "maxLength": 255, "description": "Not stored on the address itself — resolved through a tax-location name lookup, falling back to Portugal." } } }, "reference": { "type": "string", "example": "999", "maxLength": 255 }, "observations": { "type": "string", "example": "Observations", "description": "No enforced character limit (text column)." }, "retention": { "type": "string", "example": "0" }, "tax_exemption": { "type": "string", "example": "M01" }, "sequence_id": { "type": "string", "example": "12345" }, "manual_sequence_number": { "type": "string", "example": "1", "maxLength": 255, "description": "255-character limit is the database column default, not an explicit business rule." }, "client": { "type": "object", "description": "To identify an existing client, send `id`, `code`, or `name` — not all three are required. Resolution priority: if `id` is sent and matches a client on the account, that client is used and `name`/`code` are ignored. Without `id`, if `code` matches an existing client, that client is used and `name` is not needed. Without an `id`/`code` match, `name` is used to find or create the client. Creating a brand-new client (no `id`/`code` match) still requires `name`; `code` is always optional and is never generated automatically by InvoiceXpress.", "properties": { "id": { "type": "integer", "example": 1310176, "description": "Internal client ID. Preferred way to identify an existing client — see the object description." }, "name": { "type": "string", "example": "Client Name", "maxLength": 100 }, "code": { "type": "string", "example": "A1", "maxLength": 255, "description": "255-character limit is the database column default, not an explicit business rule." }, "email": { "type": "string", "example": "foo@bar.com", "maxLength": 254 }, "address": { "type": "string", "example": "Saldanha", "description": "No enforced character limit (text column)." }, "city": { "type": "string", "example": "Lisbon", "maxLength": 255, "description": "255-character limit is the database column default, not an explicit business rule." }, "postal_code": { "type": "string", "example": "1050-555", "maxLength": 255, "description": "255-character limit is the database column default, not an explicit business rule." }, "country": { "type": "string", "example": "Portugal", "maxLength": 255, "description": "255-character limit is the database column default, not an explicit business rule." }, "fiscal_id": { "type": "string", "example": "508000000", "maxLength": 255, "description": "255-character limit is the database column default, not an explicit business rule." }, "website": { "type": "string", "example": "www.website.com", "maxLength": 60 }, "phone": { "type": "string", "example": "910000000", "maxLength": 20 }, "fax": { "type": "string", "example": "210000000", "maxLength": 20 }, "observations": { "type": "string", "example": "Observations", "description": "No enforced character limit (text column)." } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "name", "unit_price", "quantity" ], "properties": { "name": { "type": "string", "example": "Item Name", "maxLength": 60, "description": "Maximum 60 characters. V3 rejects a longer name with HTTP 422; V2 accepts the request and silently truncates the stored value to 60 characters." }, "description": { "type": "string", "example": "Item Description", "maxLength": 200, "description": "Maximum 200 characters and 20 lines. V3 rejects a longer description with HTTP 422; V2 accepts the request and silently truncates the stored value to 200 characters." }, "unit_price": { "type": "number", "example": 100 }, "quantity": { "type": "number", "example": 5 }, "unit": { "type": "string", "example": "service", "description": "Restricted to a fixed set of unit values rather than length-limited free text." }, "discount": { "type": "number", "example": 50 }, "tax": { "type": "object", "properties": { "name": { "type": "string", "example": "IVA23" } } } } } }, "tax_exemption_reason": { "type": "string", "example": "M00", "maxLength": 210, "description": "Validated at 210 characters by the document model, below the 255-character database column limit." }, "load_site": { "type": "string", "example": "Lisbon, Portugal", "description": "No enforced character limit (text column)." }, "delivery_site": { "type": "string", "example": "Madrid, Spain", "description": "No enforced character limit (text column)." } } } } }, "Saft200Response": { "type": "object", "properties": { "url": { "type": "string", "description": "Link to download your SAF-T file. Absent when there are no documents to export in the selected period — see message instead.", "example": "https://some.url" }, "message": { "type": "string", "description": "Present instead of url when there are no documents to export in the selected period.", "example": "There aren't any documents to export on the selected period." } } }, "Saft202Response": { "type": "object", "properties": { "message": { "type": "string", "example": "The SAF-T file generation was started. Please keep requesting until you get back the url." } } }, "Saft500Response": { "type": "object", "properties": { "message": { "type": "string", "example": "Error generating SAF-T. Please try again." } } }, "Saft422Response": { "type": "object", "properties": { "message": { "type": "string", "example": "There aren't any documents to export on the selected period." } } }, "SequenceResponse": { "type": "object", "properties": { "sequences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 146090 }, "serie": { "type": "string", "example": "2022", "maxLength": 35 }, "default_sequence": { "type": "integer", "example": 1 }, "current_invoice_number": { "type": "integer", "example": 0 }, "current_invoice_sequence_id": { "type": "integer", "example": 146090 }, "current_invoice_validation_code": { "type": "string", "example": "ABCD1230" }, "current_invoice_receipt_number": { "type": "integer", "example": 0 }, "current_invoice_receipt_sequence_id": { "type": "integer", "example": 146092 }, "current_invoice_receipt_validation_code": { "type": "string", "example": "ABCD1231" }, "current_simplified_invoice_number": { "type": "integer", "example": 0 }, "current_simplified_invoice_sequence_id": { "type": "integer", "example": 146091 }, "current_simplified_invoice_validation_code": { "type": "string", "example": "ABCD1232" }, "current_credit_note_number": { "type": "integer", "example": 0 }, "current_credit_note_sequence_id": { "type": "integer", "example": 146095 }, "current_credit_note_validation_code": { "type": "string", "example": "ABCD1233" }, "current_debit_note_number": { "type": "integer", "example": 0 }, "current_debit_note_sequence_id": { "type": "integer", "example": 146094 }, "current_debit_note_validation_code": { "type": "string", "example": "ABCD1234" }, "current_receipt_number": { "type": "integer", "example": 0 }, "current_receipt_sequence_id": { "type": "integer", "example": 146093 }, "current_receipt_validation_code": { "type": "string", "example": "ABCD1235" }, "current_shipping_number": { "type": "integer", "example": 0 }, "current_shipping_sequence_id": { "type": "integer", "example": 146104 }, "current_shipping_validation_code": { "type": "string", "example": "ABCD1236" }, "current_transport_number": { "type": "integer", "example": 0 }, "current_transport_sequence_id": { "type": "integer", "example": 146106 }, "current_transport_validation_code": { "type": "string", "example": "ABCD1237" }, "current_devolution_number": { "type": "integer", "example": 0 }, "current_devolution_sequence_id": { "type": "integer", "example": 146105 }, "current_devolution_validation_code": { "type": "string", "example": "ABCD1238" }, "current_proforma_number": { "type": "integer", "example": 0 }, "current_proforma_sequence_id": { "type": "integer", "example": 146102 }, "current_proforma_validation_code": { "type": "string", "example": "ABCD1239" }, "current_quote_number": { "type": "integer", "example": 0 }, "current_quote_sequence_id": { "type": "integer", "example": 146101 }, "current_quote_validation_code": { "type": "string", "example": "ABCD1240" }, "current_fees_note_number": { "type": "integer", "example": 0 }, "current_fees_note_sequence_id": { "type": "integer", "example": 146103 }, "current_fees_note_validation_code": { "type": "string", "example": "N/D" }, "current_vat_moss_invoice_number": { "type": "integer", "example": 0 }, "current_vat_moss_invoice_sequence_id": { "type": "integer", "example": 146097 }, "current_vat_moss_invoice_validation_code": { "type": "string", "example": "N/A" }, "current_vat_moss_credit_note_number": { "type": "integer", "example": 0 }, "current_vat_moss_credit_note_sequence_id": { "type": "integer", "example": 146098 }, "current_vat_moss_credit_note_validation_code": { "type": "string", "example": "N/A" }, "current_vat_moss_receipt_number": { "type": "integer", "example": 0 }, "current_vat_moss_receipt_sequence_id": { "type": "integer", "example": 146099 }, "current_vat_moss_receipt_validation_code": { "type": "string", "example": "N/A" } } } } } }, "SequenceGetResponse": { "type": "object", "properties": { "sequence": { "type": "object", "properties": { "id": { "type": "integer", "example": 146090 }, "serie": { "type": "string", "example": "2022", "maxLength": 35 }, "default_sequence": { "type": "integer", "example": 1 }, "current_invoice_number": { "type": "integer", "example": 0 }, "current_invoice_sequence_id": { "type": "integer", "example": 146090 }, "current_invoice_validation_code": { "type": "string", "example": "ABCD1230" }, "current_invoice_receipt_number": { "type": "integer", "example": 0 }, "current_invoice_receipt_sequence_id": { "type": "integer", "example": 146092 }, "current_invoice_receipt_validation_code": { "type": "string", "example": "ABCD1231" }, "current_simplified_invoice_number": { "type": "integer", "example": 0 }, "current_simplified_invoice_sequence_id": { "type": "integer", "example": 146091 }, "current_simplified_invoice_validation_code": { "type": "string", "example": "ABCD1232" }, "current_credit_note_number": { "type": "integer", "example": 0 }, "current_credit_note_sequence_id": { "type": "integer", "example": 146095 }, "current_credit_note_validation_code": { "type": "string", "example": "ABCD1233" }, "current_debit_note_number": { "type": "integer", "example": 0 }, "current_debit_note_sequence_id": { "type": "integer", "example": 146094 }, "current_debit_note_validation_code": { "type": "string", "example": "ABCD1234" }, "current_receipt_number": { "type": "integer", "example": 0 }, "current_receipt_sequence_id": { "type": "integer", "example": 146093 }, "current_receipt_validation_code": { "type": "string", "example": "ABCD1235" }, "current_shipping_number": { "type": "integer", "example": 0 }, "current_shipping_sequence_id": { "type": "integer", "example": 146104 }, "current_shipping_validation_code": { "type": "string", "example": "ABCD1236" }, "current_transport_number": { "type": "integer", "example": 0 }, "current_transport_sequence_id": { "type": "integer", "example": 146106 }, "current_transport_validation_code": { "type": "string", "example": "ABCD1237" }, "current_devolution_number": { "type": "integer", "example": 0 }, "current_devolution_sequence_id": { "type": "integer", "example": 146105 }, "current_devolution_validation_code": { "type": "string", "example": "ABCD1238" }, "current_proforma_number": { "type": "integer", "example": 0 }, "current_proforma_sequence_id": { "type": "integer", "example": 146102 }, "current_proforma_validation_code": { "type": "string", "example": "ABCD1239" }, "current_quote_number": { "type": "integer", "example": 0 }, "current_quote_sequence_id": { "type": "integer", "example": 146101 }, "current_quote_validation_code": { "type": "string", "example": "ABCD1240" }, "current_fees_note_number": { "type": "integer", "example": 0 }, "current_fees_note_sequence_id": { "type": "integer", "example": 146103 }, "current_fees_note_validation_code": { "type": "string", "example": "N/D" }, "current_vat_moss_invoice_number": { "type": "integer", "example": 0 }, "current_vat_moss_invoice_sequence_id": { "type": "integer", "example": 146097 }, "current_vat_moss_invoice_validation_code": { "type": "string", "example": "N/A" }, "current_vat_moss_credit_note_number": { "type": "integer", "example": 0 }, "current_vat_moss_credit_note_sequence_id": { "type": "integer", "example": 146098 }, "current_vat_moss_credit_note_validation_code": { "type": "string", "example": "N/A" }, "current_vat_moss_receipt_number": { "type": "integer", "example": 0 }, "current_vat_moss_receipt_sequence_id": { "type": "integer", "example": 146099 }, "current_vat_moss_receipt_validation_code": { "type": "string", "example": "N/A" } } } } }, "SequenceCreateRequest": { "type": "object", "required": [ "sequence" ], "properties": { "sequence": { "type": "object", "required": [ "serie" ], "properties": { "serie": { "type": "string", "description": "Series name. ASCII letters, digits and the separators `.`, `-`, `_` only. It cannot start with `at` (any case), cannot be `trial` or `INVOICEXPRESSDEMO`, cannot start or end with a separator, and cannot have two separators in a row. Otherwise the request fails with 422 code `001`.", "example": "2023", "minLength": 1, "maxLength": 35 }, "default_sequence": { "type": "string", "description": "If \"1\" or \"true\", this sequence is chosen as the default sequence. Other values are ignored.", "example": "1" } } } } }, "Sequence006Response": { "type": "object", "properties": { "errors": { "type": "object", "properties": { "code": { "type": "string", "example": "006" }, "message": { "type": "string", "example": "The sequence doesn't exist." } } } } }, "Sequence005Response": { "type": "object", "properties": { "errors": { "type": "object", "properties": { "code": { "type": "string", "example": "005" }, "message": { "type": "string", "example": "All sequences are registered." } } } } }, "Sequence001Response": { "type": "object", "properties": { "errors": { "type": "object", "properties": { "code": { "type": "string", "example": "001" }, "message": { "type": "string", "example": "Sequence name not allowed." } } } } }, "TaxesResponse": { "type": "object", "properties": { "taxes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 31554 }, "name": { "type": "string", "example": "IVA23", "maxLength": 255 }, "value": { "type": "string", "example": "23.0" }, "region": { "type": "string", "example": "PT" }, "code": { "type": "string", "example": "NOR", "maxLength": 255 }, "default_tax": { "type": "integer", "example": 1, "description": "1 if it is the default tax, 0 otherwise" } } } } } }, "TaxesGetResponse": { "type": "object", "properties": { "tax": { "type": "object", "properties": { "id": { "type": "integer", "example": 31540 }, "name": { "type": "string", "example": "IVA23", "maxLength": 255 }, "value": { "type": "string", "example": "23.0" }, "region": { "type": "string", "example": "PT" }, "code": { "type": "string", "example": "NOR", "maxLength": 255 }, "default_tax": { "type": "integer", "example": 1, "description": "1 if it is the default tax, 0 otherwise" } } } } }, "TaxesCreateRequest": { "type": "object", "required": [ "tax" ], "properties": { "tax": { "type": "object", "required": [ "name", "value", "region" ], "properties": { "name": { "type": "string", "description": "Tax name", "example": "IVA23", "maxLength": 255 }, "value": { "type": "string", "description": "Tax value (%), between 0 and 100. A comma decimal separator is accepted.", "example": "23.0" }, "region": { "type": "string", "description": "Tax region. Required, except for the exempt tax named `Isento`.\n\nMust be one of: `PT`, `PT-AC`, `PT-MA`, or an ISO country code.\n", "example": "PT" }, "code": { "type": "string", "description": "Tax code.\n\nMust be one of: `NOR` (Normal), `INT` (Intermediate), `RED` (Reduced), `OUT` (Other), `ISE` (Exempt).\n\nNot validated server-side. If left blank, it defaults to `NOR`.\n", "enum": [ "NOR", "INT", "RED", "OUT", "ISE" ], "example": "NOR" }, "default_tax": { "type": "integer", "description": "If \"1\", the tax is chosen as the default tax on your account.", "example": 1 } } } } }, "422UpdateTaxes": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string", "example": "Região não pode estar vazio" } } } } } }, "422CreateTaxes": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string", "example": "Nome já está em uso" } } } } } }, "ClientsListAll": { "type": "object", "properties": { "clients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 89895780 }, "name": { "type": "string", "example": "Client Name", "maxLength": 100 }, "code": { "type": [ "string", "null" ], "example": "12345", "maxLength": 255, "description": "Maximum length is the database default, not an enforced business rule." }, "email": { "type": [ "string", "null" ], "example": "foo@bar.com", "maxLength": 254 }, "language": { "type": [ "string", "null" ], "example": "pt", "maxLength": 255, "description": "Maximum length is the database default, not an enforced business rule." }, "address": { "type": [ "string", "null" ], "example": "Avenida da República, Lisboa", "description": "No enforced character limit (text column)." }, "city": { "type": [ "string", "null" ], "example": "Lisboa", "maxLength": 255, "description": "Maximum length is the database default, not an enforced business rule." }, "postal_code": { "type": [ "string", "null" ], "example": "1050-555", "maxLength": 255, "description": "Maximum length is the database default, not an enforced business rule." }, "country": { "type": [ "string", "null" ], "example": "Portugal", "maxLength": 255, "description": "Omitted entirely for clients with no country set. Maximum length is the database default, not an enforced business rule." }, "fiscal_id": { "type": [ "string", "null" ], "example": "508025338", "maxLength": 255, "description": "Maximum length is the database default, not an enforced business rule." }, "website": { "type": [ "string", "null" ], "example": "www.invoicexpress.com", "maxLength": 60 }, "phone": { "type": [ "string", "null" ], "example": "213456789", "maxLength": 20 }, "fax": { "type": [ "string", "null" ], "example": "213456788", "maxLength": 20 }, "preferred_contact": { "type": "object", "description": "May be an empty object when no preferred contact is set.", "properties": { "name": { "type": [ "string", "null" ], "example": "Bruce Norris", "maxLength": 255, "description": "Contact-level name has no length validation, unlike the client-level `name` (max 100); the limit shown is the database default." }, "email": { "type": [ "string", "null" ], "example": "email@invoicexpress.com", "maxLength": 255, "description": "Contact-level email allows one character more than the client-level `email` (max 254)." }, "phone": { "type": [ "string", "null" ], "example": "213456789", "maxLength": 255, "description": "Contact-level phone has no length validation, unlike the client-level `phone` (max 20); the limit shown is the database default." }, "mobile": { "type": [ "string", "null" ], "example": null, "minLength": 4, "maxLength": 14, "description": "Digits only (4-14). Validated against /\\A\\d{4,14}\\z/." } } }, "observations": { "type": [ "string", "null" ], "example": null, "description": "No enforced character limit (text column)." }, "send_options": { "type": [ "integer", "null" ], "example": 1 } } } }, "pagination": { "type": "object", "properties": { "total_entries": { "type": "integer", "example": 6 }, "current_page": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 10 } } } } }, "ClientsGetResponse": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "integer", "example": 196601767 }, "name": { "type": "string", "example": "Ricardo Pereira", "maxLength": 100 }, "code": { "type": [ "string", "null" ], "example": null, "maxLength": 255, "description": "Maximum length is the database default, not an enforced business rule." }, "language": { "type": [ "string", "null" ], "example": "pt", "maxLength": 255, "description": "Maximum length is the database default, not an enforced business rule." }, "email": { "type": [ "string", "null" ], "example": "someone@example.com", "maxLength": 254 }, "address": { "type": [ "string", "null" ], "example": "Lisbon", "description": "No enforced character limit (text column)." }, "city": { "type": [ "string", "null" ], "example": "Lisbon", "maxLength": 255, "description": "Maximum length is the database default, not an enforced business rule." }, "postal_code": { "type": [ "string", "null" ], "example": "1750-455", "maxLength": 255, "description": "Maximum length is the database default, not an enforced business rule." }, "fiscal_id": { "type": [ "string", "null" ], "example": "508025338", "maxLength": 255, "description": "Maximum length is the database default, not an enforced business rule." }, "website": { "type": [ "string", "null" ], "example": "www.invoicexpress.com", "maxLength": 60 }, "country": { "type": [ "string", "null" ], "example": "Portugal", "maxLength": 255, "description": "Maximum length is the database default, not an enforced business rule." }, "phone": { "type": [ "string", "null" ], "example": "2313423424", "maxLength": 20 }, "fax": { "type": [ "string", "null" ], "example": "2313423425", "maxLength": 20 }, "preferred_contact": { "type": "object", "description": "May be an empty object when no preferred contact is set.", "properties": { "name": { "type": [ "string", "null" ], "example": "Ricardo Pereira", "maxLength": 255, "description": "Contact-level name has no length validation, unlike the client-level `name` (max 100); the limit shown is the database default." }, "email": { "type": [ "string", "null" ], "example": "someone@example.com", "maxLength": 255, "description": "Contact-level email allows one character more than the client-level `email` (max 254)." }, "phone": { "type": [ "string", "null" ], "example": "2233442233", "maxLength": 255, "description": "Contact-level phone has no length validation, unlike the client-level `phone` (max 20); the limit shown is the database default." }, "mobile": { "type": [ "string", "null" ], "example": null, "minLength": 4, "maxLength": 14, "description": "Digits only (4-14). Validated against /\\A\\d{4,14}\\z/." } } }, "observations": { "type": [ "string", "null" ], "example": null, "description": "No enforced character limit (text column)." }, "open_account_link": { "type": "string", "example": "https://www.app.invoicexpress.com/suppliers/1f7bba947948c50e04af20d329db5bc67c38cf89" }, "send_options": { "type": [ "integer", "null" ], "example": 1 }, "payment_days": { "type": [ "integer", "null" ], "example": 0 }, "tax_exemption_code": { "type": [ "string", "null" ], "example": "M00", "maxLength": 255, "description": "Maximum length is the database default, not an enforced business rule." } } } } }, "ClientRequest": { "type": "object", "required": [ "client" ], "properties": { "client": { "type": "object", "required": [ "name", "code" ], "properties": { "name": { "type": "string", "example": "Client Name", "maxLength": 100 }, "code": { "type": "string", "example": "12345", "maxLength": 255, "description": "Maximum length is the database default, not an enforced business rule." }, "email": { "type": "string", "example": "foo@bar.com", "maxLength": 254 }, "language": { "type": "string", "enum": [ "en", "pt", "es" ], "example": "pt" }, "address": { "type": "string", "example": "Avenida da República, Lisboa", "description": "No enforced character limit (text column)." }, "city": { "type": "string", "example": "Lisboa", "maxLength": 255, "description": "Maximum length is the database default, not an enforced business rule." }, "postal_code": { "type": "string", "example": "1050-555", "maxLength": 255, "description": "Maximum length is the database default, not an enforced business rule." }, "country": { "type": "string", "example": "Portugal", "maxLength": 255, "description": "Maximum length is the database default, not an enforced business rule." }, "fiscal_id": { "type": "string", "example": "508025338", "maxLength": 255, "description": "Maximum length is the database default, not an enforced business rule." }, "website": { "type": "string", "example": "www.invoicexpress.com", "maxLength": 60 }, "phone": { "type": "string", "example": "213456789", "maxLength": 20 }, "fax": { "type": "string", "example": "213456788", "maxLength": 20 }, "preferred_contact": { "type": "object", "description": "The preferred contact details.", "properties": { "name": { "type": "string", "example": "Bruce Norris", "maxLength": 255, "description": "Contact-level name has no length validation, unlike the client-level `name` (max 100); the limit shown is the database default." }, "email": { "type": "string", "example": "email@invoicexpress.com", "maxLength": 255, "description": "Contact-level email allows one character more than the client-level `email` (max 254)." }, "phone": { "type": "string", "example": "213456789", "maxLength": 255, "description": "Contact-level phone has no length validation, unlike the client-level `phone` (max 20); the limit shown is the database default." } } }, "observations": { "type": "string", "example": "Observations", "description": "No enforced character limit (text column)." }, "send_options": { "type": "string", "enum": [ "1", "2", "3" ], "example": "1" } } } } }, "ClientsInvoicesResponse": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 541793 }, "status": { "type": "string", "example": "final" }, "cancel_reason": { "type": "string", "description": "Only present once the document has been canceled — carries the message supplied to change-state.", "example": "document was duplicated" }, "archived": { "type": "boolean", "example": true }, "type": { "type": "string", "example": "Invoice" }, "sequence_number": { "type": "string", "example": "28/A" }, "inverted_sequence_number": { "type": "string", "example": "A/28" }, "date": { "type": "string", "example": "27/06/2017" }, "due_date": { "type": "string", "example": "27/06/2017" }, "reference": { "type": [ "string", "null" ], "example": "foo" }, "observations": { "type": [ "string", "null" ], "example": "foo" }, "retention": { "type": [ "string", "null" ], "example": null }, "atcud": { "type": "string", "example": "N/D" }, "permalink": { "type": "string", "example": "https://web.invoicexpress.com/documents/..." }, "saft_hash": { "type": "string", "description": "Only present once the document has been finalized.", "example": "Tdik" }, "sum": { "type": "number", "example": 1 }, "discount": { "type": [ "number", "null" ], "example": 0 }, "before_taxes": { "type": "number", "example": 1 }, "taxes": { "type": "number", "example": 0.07 }, "total": { "type": "number", "example": 1.07 }, "currency": { "type": "string", "example": "Euro" }, "client": { "type": "object", "properties": { "id": { "type": "integer", "example": 1310176 }, "name": { "type": "string", "example": "John" }, "email": { "type": [ "string", "null" ], "example": "john@example.com" }, "address": { "type": [ "string", "null" ], "example": "Avenida da República, Lisboa" }, "postal_code": { "type": [ "string", "null" ], "example": "1050-555" }, "city": { "type": [ "string", "null" ], "example": "Lisboa" }, "fiscal_id": { "type": [ "string", "null" ], "example": "508025338" }, "country": { "type": "string", "example": "Portugal" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": " iPhone " }, "description": { "type": [ "string", "null" ], "example": "foo" }, "unit_price": { "type": "string", "example": "1.0" }, "unit": { "type": [ "string", "null" ], "example": "foo" }, "quantity": { "type": "string", "example": "1.0" }, "tax": { "type": "object", "properties": { "id": { "type": "integer", "example": 31597 }, "name": { "type": "string", "example": "IVA7" }, "value": { "type": "number", "example": 7 } } }, "discount": { "type": "number", "example": 0 }, "subtotal": { "type": "number", "example": 1 }, "tax_amount": { "type": "number", "example": 0.07 }, "discount_amount": { "type": "number", "example": 0 }, "total": { "type": "number", "example": 1.07 } } } }, "sequence_id": { "type": [ "integer", "null" ], "description": "Absent while the document is still a draft.", "example": 12345 }, "tax_exemption": { "type": "string", "description": "Absent unless a tax exemption applies.", "example": "M01" } } } }, "pagination": { "type": "object", "properties": { "total_entries": { "type": "integer", "example": 6 }, "current_page": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 10 } } } } }, "ClientsInvoiceFilterRequest": { "type": "object", "properties": { "filter": { "type": "object", "description": "Filters to apply on the list", "properties": { "status": { "type": "array", "items": { "type": "string" }, "example": [ "final" ] }, "by_type": { "type": "array", "items": { "type": "string" }, "example": [ "Invoice" ] }, "archived": { "type": "array", "items": { "type": "string" }, "example": [ "non_archived" ] } } } } }, "422CreateClients": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string", "example": "Nome não pode ficar em branco" } } } } } }, "ItemsListAll": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 402322 }, "name": { "type": "string", "example": "Large", "maxLength": 60 }, "description": { "type": [ "string", "null" ], "example": "foo", "maxLength": 200 }, "unit_price": { "type": "string", "example": "24.3902" }, "unit": { "type": "string", "example": "service", "description": "One of: `hour`, `day`, `month`, `unit`, `service`, `tax`, `other`, `product`, `article`." }, "tax": { "type": "object", "properties": { "name": { "type": "string", "example": "IVA23" }, "value": { "type": "string", "example": "23.0" }, "comment": { "type": "string", "example": "tax value:23.0%" } } } } } } } }, "ItemsGetResponse": { "type": "object", "properties": { "item": { "type": "object", "properties": { "id": { "type": "integer", "example": 402321 }, "name": { "type": "string", "example": "Medium", "maxLength": 60 }, "description": { "type": [ "string", "null" ], "example": "foo", "maxLength": 200 }, "unit_price": { "type": "string", "example": "16.2602" }, "unit": { "type": "string", "example": "service", "description": "One of: `hour`, `day`, `month`, `unit`, `service`, `tax`, `other`, `product`, `article`." }, "tax": { "type": "object", "properties": { "name": { "type": "string", "example": "IVA23" }, "value": { "type": "string", "example": "23.0" }, "comment": { "type": "string", "example": "tax value:23.0%" } } } } } } }, "ItemRequest": { "type": "object", "required": [ "item" ], "properties": { "item": { "type": "object", "required": [ "name", "unit_price" ], "properties": { "name": { "type": "string", "example": "Item name", "maxLength": 60, "description": "Item name. Values longer than 60 characters are rejected with HTTP 422 — they are not truncated." }, "description": { "type": "string", "example": "Item description", "maxLength": 200, "description": "Item description. Values longer than 200 characters are rejected with HTTP 422 — they are not truncated." }, "unit_price": { "type": "number", "example": 9.99 }, "unit": { "type": "string", "example": "service", "description": "One of: `hour`, `day`, `month`, `unit`, `service`, `tax`, `other`, `product`, `article`." }, "tax": { "type": "object", "properties": { "name": { "type": "string", "example": "IVA23" } } } } } } }, "422UpdateItems": { "type": "object", "description": "Validation errors come as objects with an `error` field. An unknown `tax.name` is the exception: it returns a list of strings, e.g. `{\"errors\":[\"Tax not found.\"]}`.", "properties": { "errors": { "type": "array", "description": "Lista de objetos contendo mensagens de erro detalhadas.", "items": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": [ { "error": "Name is not available." }, { "error": "Name can't be changed because it is already associated with invoices" }, { "error": "Price is not valid. Check the decimal mark and if you are inserting only numbers." } ] } } }, "422CreateItems": { "type": "object", "properties": { "errors": { "type": "array", "description": "Lista de objetos contendo mensagens de erro detalhadas.", "items": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": [ { "error": "Price is a required field" }, { "error": "RRP is a required field" }, { "error": "Name is a required field" } ] } } }, "ClientBalanceResponse": { "type": "object", "properties": { "currency": { "type": "object", "properties": { "symbol": { "type": "string", "example": "€" }, "code": { "type": "string", "example": "EUR" } } }, "initial_balance": { "type": "object", "properties": { "value": { "type": "number", "example": 0 }, "created_at": { "type": "string", "format": "date", "example": "1970-01-01" }, "observation": { "type": [ "string", "null" ], "example": null } } }, "balance": { "type": "object", "properties": { "with_vat": { "type": "number", "example": 0 } } }, "overdue_balance": { "type": "object", "properties": { "with_vat": { "type": "number", "example": 0 } } }, "remaining_balance": { "type": "object", "properties": { "total": { "type": "number", "example": 0 }, "value": { "type": "number", "example": 0 } } } } }, "InitialBalanceRequest": { "type": "object", "required": [ "initial_balance" ], "properties": { "initial_balance": { "type": "object", "required": [ "value", "date" ], "properties": { "value": { "type": "number", "example": 123.45 }, "date": { "type": "string", "example": "2023-05-19" }, "observation": { "type": [ "string", "null" ], "example": null } } } } }, "RegularizationListResponse": { "type": "object", "properties": { "regularization": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "number": { "type": "string", "example": "NR00000001" }, "value": { "type": "number", "example": 123.45 }, "date": { "type": "string", "format": "date", "example": "2023-05-19" }, "observation": { "type": [ "string", "null" ], "example": null } } } }, "pagination": { "type": "object", "properties": { "total_entries": { "type": "integer", "example": 1 }, "current_page": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 10 } } } } }, "RegularizationRequest": { "type": "object", "required": [ "regularization" ], "properties": { "regularization": { "type": "object", "required": [ "value", "date" ], "properties": { "value": { "type": "number", "example": 123.45 }, "date": { "type": "string", "example": "2023-08-24" }, "observation": { "type": [ "string", "null" ], "example": null } } } } }, "TreasuryMovementRequest": { "type": "object", "required": [ "treasury_movement" ], "properties": { "treasury_movement": { "type": "object", "required": [ "value", "movement_type", "date" ], "properties": { "value": { "type": "number", "example": 123.45 }, "movement_type": { "type": "string", "enum": [ "Reimbursement", "Payment" ], "example": "Reimbursement" }, "payment_method": { "type": "string", "description": "Treasury movement can be CC “Cartão de crédito”, CD “Cartão de débito”, CH “Cheque bancário”, CI “Crédito documentário internacional”, CO “Cheque ou cartão oferta”, CS “Compensação de saldos de conta corrente”, DE “Dinheiro electrónico”, LC “Letra comercial”, MB “Referências de pagamento para Multibanco”, NU “Numerário”, or “Outros meios aqui não assinalados”, PR “Permuta de bens”, TB “Transferência bancária ou débito direto autorizado”, TR “Ticket restaurante”", "example": "MB" }, "date": { "type": "string", "example": "2023-04-28", "description": "A `date` string that cannot be parsed (for example `31/02/2023`) is replaced by today's date." }, "document_id": { "type": "integer", "example": 246711205, "description": "Optional. Document the movement relates to." }, "serie": { "type": "string", "example": "2023" }, "observation": { "type": "string", "example": "Payment observation" } } } } }, "TreasuryMovementResponse": { "type": "object", "properties": { "treasury_movement": { "type": "object", "properties": { "value": { "type": "number", "example": 123.45 }, "movement_type": { "type": "string", "example": "Reimbursement" }, "payment_method": { "type": "string", "example": "MB" }, "date": { "type": "string", "format": "date", "example": "2023-04-28" }, "serie": { "type": "string", "example": "2023" }, "observation": { "type": [ "string", "null" ], "example": null } } } } }, "InitialBalanceResponse": { "type": "object", "properties": { "initial_balance": { "type": "object", "properties": { "value": { "type": "number", "example": 123.45 }, "date": { "type": "string", "format": "date", "example": "2023-05-19" }, "observation": { "type": [ "string", "null" ], "example": null } } } } }, "404Clients": { "type": "object", "properties": { "errors": { "type": "array", "description": "List of errors returned when the client is not found.", "items": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": [ { "error": "Client not found" } ] } } }, "404TreasuryMovement": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": [ { "error": "Client not found" }, { "error": "Reimbursement not found" } ] } } }, "404Taxes": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" }, "example": [ "Tax not found." ] } } }, "404Client": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" }, "example": [ "Client not found." ] } } }, "404Items": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" }, "example": [ "Item not found." ] } } }, "202Pdf": { "type": "object", "properties": { "pdf": { "type": "object", "properties": { "message": { "type": "string", "example": "PDF file is being generated" } } } } }, "TaxesUpdateRequest": { "type": "object", "required": [ "tax" ], "properties": { "tax": { "type": "object", "description": "Partial update: send only the fields to change.", "properties": { "name": { "type": "string", "description": "Tax name", "example": "IVA23", "maxLength": 255 }, "value": { "type": "string", "description": "Tax value (%), between 0 and 100. A comma decimal separator is accepted.", "example": "23.0" }, "region": { "type": "string", "description": "Cannot be cleared, except on the exempt tax named `Isento`.\n\nMust be one of: `PT`, `PT-AC`, `PT-MA`, or an ISO country code.\n", "example": "PT" }, "code": { "type": "string", "description": "Tax code.\n\nMust be one of: `NOR` (Normal), `INT` (Intermediate), `RED` (Reduced), `OUT` (Other), `ISE` (Exempt).\n\nNot validated server-side. If sent blank, it is set to `NOR`; if not sent, it is unchanged.\n", "enum": [ "NOR", "INT", "RED", "OUT", "ISE" ], "example": "NOR" }, "default_tax": { "type": "integer", "description": "If \"1\", the tax is chosen as the default tax on your account.", "example": 1 } } } } }, "404Regularization": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": [ { "error": "Regularization not found" }, { "error": "Client not found" } ] } } }, "404GeneratePayment": { "type": "array", "description": "List of `[field, message]` pairs.", "items": { "type": "array", "items": { "type": "string" } }, "example": [ [ "base", "document not found" ] ] }, "422InitialBalance": { "type": "object", "properties": { "errors": { "type": "array", "description": "List of initial balance validation errors.", "items": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": [ { "error": "Date can't be blank" } ] } } }, "422CreateRegularization": { "type": "object", "properties": { "errors": { "type": "array", "description": "List of validation errors when creating a regularization.", "items": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": [ { "error": "The regularization amount must be less than or equal to the remaining balance" }, { "error": "Date can't be blank" } ] } } }, "RegularizationCreateResponse": { "type": "object", "properties": { "regularization": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "number": { "type": "string", "example": "NR00000001" }, "value": { "type": "number", "example": 123.45 }, "date": { "type": "string", "format": "date", "example": "2023-05-19" }, "observation": { "type": [ "string", "null" ], "example": null } } } } }, "422Treasury": { "type": "object", "properties": { "errors": { "type": "array", "description": "List of validation errors for a treasury movement.", "items": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": [ { "error": "Validation failed: Value is not a number" }, { "error": "The receipt amount must be less than or equal to the outstanding balance of the documents." }, { "error": "Value of reimbursement must be less than or equal to the settled balance of the documents" }, { "error": "This request was already sent with a different payload. Use a new Idempotency-Key for a new payment." } ] } } }, "InvoiceGetResponse": { "type": "object", "description": "Returned by the create, get, update, and change-state endpoints for `{invoices-type}` documents. The parent key shown here as `invoice` is only an example — the actual key always matches the singular of the requested `{invoices-type}` path parameter: `invoice` for `invoices`, `invoice_receipt` for `invoice_receipts`, `simplified_invoice` for `simplified_invoices`, `credit_note` for `credit_notes`, and `debit_note` for `debit_notes`. The nested object shape is identical in every case.", "properties": { "invoice": { "$ref": "#/components/schemas/FullDocumentObject" } } }, "EstimateGetResponse": { "type": "object", "properties": { "quote": { "type": "object", "properties": { "id": { "type": "integer", "example": 541791 }, "status": { "type": "string", "example": "final" }, "archived": { "type": "boolean", "example": false }, "type": { "type": "string", "enum": [ "Quote", "Proforma", "FeesNote" ], "example": "Quote" }, "sequence_number": { "type": "string", "example": "1/A" }, "inverted_sequence_number": { "type": "string", "example": "A/1" }, "atcud": { "type": "string", "example": "ABCD1234-1" }, "date": { "type": "string", "example": "12/06/2017" }, "due_date": { "type": "string", "example": "12/06/2017" }, "reference": { "type": [ "string", "null" ], "example": null, "maxLength": 255 }, "observations": { "type": [ "string", "null" ], "example": "foo", "description": "No enforced character limit (text column)." }, "retention": { "type": [ "string", "null" ], "example": null }, "permalink": { "type": "string", "example": "https://web.invoicexpress.com/documents/541791f16ae45a73b703c684a221ef198c10020f3d56a1" }, "saft_hash": { "type": "string", "example": "NfTN", "description": "Server-generated. No enforced character limit (text column)." }, "sum": { "type": "number", "example": 10 }, "discount": { "type": "number", "example": 0 }, "before_taxes": { "type": "number", "example": 10 }, "taxes": { "type": "number", "example": 2.3 }, "total": { "type": "number", "example": 12.3 }, "currency": { "type": "string", "example": "Euro" }, "sequence_id": { "type": [ "integer", "null" ], "example": 12345 }, "tax_exemption": { "type": "string", "example": "M01", "maxLength": 255 }, "cancel_reason": { "type": "string", "description": "Only present when the document is canceled.", "example": "Wrong client" }, "mb_reference": { "$ref": "#/components/schemas/MbReference", "description": "Only present when the document is final and has an MB reference." }, "multicurrency": { "type": "object", "description": "Only present for documents in a foreign currency.", "properties": { "rate": { "type": "number", "example": 1.1 }, "currency": { "type": "string", "example": "USD" }, "total": { "type": "number", "example": 13.53 } } }, "client": { "$ref": "#/components/schemas/InvoiceClient" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceItem" } } } } } }, "InvoiceListAllResponse": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 541793 }, "status": { "type": "string", "example": "final" }, "cancel_reason": { "type": "string", "description": "Only present once the document has been canceled — carries the message supplied to change-state. No enforced character limit (text column).", "example": "document was duplicated" }, "archived": { "type": "boolean", "example": true }, "type": { "type": "string", "example": "Invoice" }, "sequence_number": { "type": "string", "example": "A/28" }, "inverted_sequence_number": { "type": "string", "example": "A/28" }, "atcud": { "type": "string", "example": "ABCD1234-28" }, "date": { "type": "string", "description": "dd/mm/yyyy", "example": "27/06/2017" }, "due_date": { "type": "string", "description": "dd/mm/yyyy", "example": "27/06/2017" }, "reference": { "type": [ "string", "null" ], "example": "fb30", "maxLength": 255 }, "observations": { "type": [ "string", "null" ], "example": "foo", "description": "No enforced character limit (text column)." }, "retention": { "type": [ "string", "null" ], "example": null }, "permalink": { "type": "string", "example": "https://web.invoicexpress.com/documents/541793e1ab2ebd5c06def40c346ffbe0ff2b463eb1c0f0" }, "saft_hash": { "type": "string", "example": "Tdik", "description": "Server-generated. No enforced character limit (text column)." }, "sum": { "type": "number", "example": 1 }, "discount": { "type": "number", "example": 0 }, "before_taxes": { "type": "number", "example": 1 }, "taxes": { "type": "number", "example": 0.07 }, "total": { "type": "number", "example": 1.07 }, "currency": { "type": "string", "example": "Euro" }, "sequence_id": { "type": [ "integer", "null" ], "example": 12345 }, "tax_exemption": { "type": "string", "example": "M01", "maxLength": 255 }, "client": { "type": "object", "properties": { "id": { "type": "integer", "example": 1310176 }, "name": { "type": "string", "example": "John" }, "code": { "type": [ "string", "null" ], "example": "CLI-001" }, "email": { "type": [ "string", "null" ], "example": "john@example.com" }, "address": { "type": [ "string", "null" ], "example": "Avenida da República, Lisboa" }, "postal_code": { "type": [ "string", "null" ], "example": "1050-555" }, "city": { "type": [ "string", "null" ], "example": "Lisboa" }, "fiscal_id": { "type": [ "string", "null" ], "example": "508025338" }, "country": { "type": "string", "example": "Portugal" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": " iPhone " }, "description": { "type": [ "string", "null" ], "example": "foo" }, "unit_price": { "type": "string", "example": "1.0" }, "unit": { "type": [ "string", "null" ], "example": "foo" }, "quantity": { "type": "string", "example": "1.0" }, "discount": { "type": "number", "example": 0 }, "subtotal": { "type": "number", "example": 1 }, "tax_amount": { "type": "number", "example": 0.07 }, "discount_amount": { "type": "number", "example": 0 }, "total": { "type": "number", "example": 1.07 }, "tax": { "type": "object", "properties": { "id": { "type": "integer", "example": 31597 }, "name": { "type": "string", "example": "IVA7" }, "value": { "type": "number", "example": 7 } } } } } } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "PaymentResponse": { "type": "object", "properties": { "receipt": { "$ref": "#/components/schemas/FullDocumentObject" } } }, "FullDocumentObject": { "type": "object", "properties": { "id": { "type": "integer", "example": 2137287 }, "status": { "type": "string", "example": "final" }, "archived": { "type": "boolean", "example": false }, "type": { "type": "string", "example": "Invoice" }, "sequence_number": { "type": "string", "example": "6/G" }, "inverted_sequence_number": { "type": "string", "example": "G/6" }, "atcud": { "type": "string", "example": "ABCD1234-6" }, "sequence_id": { "type": [ "integer", "null" ], "example": 12345 }, "tax_exemption": { "type": "string", "example": "M01", "maxLength": 255 }, "date": { "type": "string", "example": "04/08/2016" }, "due_date": { "type": "string", "example": "19/08/2016" }, "reference": { "type": [ "string", "null" ], "example": "ref123", "maxLength": 255 }, "observations": { "type": [ "string", "null" ], "example": "Observations", "description": "No enforced character limit (text column)." }, "retention": { "type": [ "string", "null" ], "example": null }, "cancel_reason": { "type": [ "string", "null" ], "description": "Present after the document has been canceled. No enforced character limit (text column).", "example": "API test cancellation" }, "permalink": { "type": "string", "example": "https://web.invoicexpress.com/documents/..." }, "saft_hash": { "type": "string", "example": "J4ay", "description": "Server-generated. No enforced character limit (text column)." }, "sum": { "type": "number", "example": 24.39 }, "discount": { "type": [ "number", "null" ], "example": 0 }, "before_taxes": { "type": "number", "example": 24.39 }, "taxes": { "type": "number", "example": 5.61 }, "total": { "type": "number", "example": 30 }, "currency": { "type": "string", "example": "Euro" }, "client": { "$ref": "#/components/schemas/InvoiceClient" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceItem" } }, "mb_reference": { "$ref": "#/components/schemas/MbReference" } } }, "InvoiceClient": { "type": "object", "description": "`id` and `name` are always present. The other fields are only returned when they have a value.", "properties": { "id": { "type": "integer", "example": 628535 }, "name": { "type": "string", "example": "John Doe" }, "code": { "type": "string", "example": "C1" }, "country": { "type": "string", "example": "Portugal" }, "email": { "type": "string", "example": "john@example.com" }, "address": { "type": "string", "example": "Avenida da República" }, "postal_code": { "type": "string", "example": "1050-555" }, "city": { "type": "string", "example": "Lisboa" }, "fiscal_id": { "type": "string", "example": "508025338" }, "website": { "type": "string", "example": "www.example.com" }, "phone": { "type": "string", "example": "910000000" }, "fax": { "type": "string", "example": "210000000" }, "observations": { "type": "string", "example": "VIP client" } } }, "InvoiceItem": { "type": "object", "properties": { "name": { "type": "string", "example": "Product A" }, "description": { "type": [ "string", "null" ], "example": "Big Product" }, "unit_price": { "type": "string", "example": "100.0" }, "quantity": { "type": "string", "example": "1.0" }, "unit": { "type": "string", "example": "un" }, "discount": { "type": "number", "example": 0 }, "tax": { "type": "object", "properties": { "id": { "type": "integer", "example": 756700 }, "name": { "type": "string", "example": "IVA23" }, "value": { "type": "number", "example": 23 } } }, "subtotal": { "type": "number", "example": 100 }, "tax_amount": { "type": "number", "example": 23 }, "discount_amount": { "type": "number", "example": 0 }, "total": { "type": "number", "example": 123 } } }, "MbReference": { "type": "object", "properties": { "entity": { "type": "string", "example": "10611" }, "reference": { "type": "string", "example": "123 456 789" }, "value": { "type": "number", "example": 123.45 } } }, "PdfResponse": { "type": "object", "properties": { "output": { "type": "object", "properties": { "pdfUrl": { "type": "string", "example": "url.pdf" }, "signed": { "type": "boolean", "example": true, "description": "Whether the PDF is digitally signed. Not always present." } } } } }, "QrCodeResponse": { "type": "object", "properties": { "qr_code": { "type": "object", "properties": { "url": { "type": "string", "example": "url.png" } } } } }, "Pagination": { "type": "object", "properties": { "total_entries": { "type": "integer", "example": 50 }, "per_page": { "type": "integer", "example": 20 }, "current_page": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 3 } } }, "422CreateAccount": { "type": "object", "properties": { "errors": { "description": "An array of validation error objects, or a plain array of strings (e.g. [\"Param is missing\"]) if a required top-level param is missing entirely.", "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string", "example": "Owner Owner is invalid" } } } }, { "type": "array", "items": { "type": "string" }, "example": [ "Param is missing" ] } ] } } }, "422UpdateAccount": { "type": "object", "properties": { "errors": { "description": "An array of validation error objects, or a plain array of strings (e.g. [\"Param is missing\"]) if a required top-level param is missing entirely.", "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string", "example": "Contribuinte não é válido" } } } }, { "type": "array", "items": { "type": "string" }, "example": [ "Param is missing" ] } ] } } }, "422AlreadyUser": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string", "example": "Terms and Conditions should be accepted" } } } } } }, "422AtCommunication": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": [ { "error": "The field communication_type can't be blank" }, { "error": "The field at_subuser has an incorrect size" } ] } } }, "422CreateInvoice": { "type": "object", "description": "English text shown; the message follows the account language.", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": [ { "error": "Date can't be blank" }, { "error": "This document is being saved by another request. Please try again." } ] } } }, "422UpdateInvoices": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string", "example": "Elemento client não fornecido" } } } } } }, "404Documents": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string", "example": "Document not found" } } } } } }, "422ChangeState": { "type": "object", "description": "English text shown; the message follows the account language.", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": [ { "error": "CantHandle: 1 for Invoice" }, { "error": "The cancellation reason is a required field" } ] } } }, "202QRCode": { "type": "object", "properties": { "qr_code": { "type": "object", "properties": { "message": { "type": "string", "example": "QR Code is being generated" } } } } }, "404QRCode": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": [ { "error": "Document not found" } ] } } }, "422QRCode": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": [ { "error": "QR code is not available for draft documents." }, { "error": "There was an error generating the QR code." } ] } } }, "200RelatedDocuments": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 541793 }, "status": { "type": "string", "example": "final" }, "archived": { "type": "boolean", "example": true }, "type": { "type": "string", "example": "Invoice" }, "sequence_number": { "type": "string", "example": "28/A" }, "inverted_sequence_number": { "type": "string", "example": "A/28" }, "atcud": { "type": "string", "example": "ABCD1234-28" }, "date": { "type": "string", "example": "27/06/2017" }, "due_date": { "type": "string", "example": "27/06/2017" }, "reference": { "type": [ "string", "null" ], "example": "foo", "maxLength": 255 }, "observations": { "type": [ "string", "null" ], "example": "foo", "description": "No enforced character limit (text column)." }, "retention": { "type": [ "string", "null" ], "example": null }, "cancel_reason": { "type": [ "string", "null" ], "description": "Present after the document has been canceled. No enforced character limit (text column).", "example": "API test cancellation" }, "permalink": { "type": "string", "example": "https://web.invoicexpress.com/documents/541793e1ab2ebd5c06def40c346ffbe0ff2b463eb1c0f0" }, "saft_hash": { "type": "string", "example": "Tdik", "description": "Server-generated. No enforced character limit (text column)." }, "sum": { "type": "number", "example": 1 }, "discount": { "type": [ "number", "null" ], "example": 0 }, "before_taxes": { "type": "number", "example": 1 }, "taxes": { "type": "number", "example": 0.07 }, "total": { "type": "number", "example": 1.07 }, "currency": { "type": "string", "example": "Euro" }, "sequence_id": { "type": [ "integer", "null" ], "example": 12345 }, "tax_exemption": { "type": "string", "example": "M01", "maxLength": 255 }, "client": { "type": "object", "properties": { "id": { "type": "integer", "example": 1310176 }, "name": { "type": "string", "example": "John" }, "country": { "type": "string", "example": "Portugal" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": " iPhone " }, "description": { "type": "string", "example": "foo" }, "unit_price": { "type": "string", "example": "1.0" }, "unit": { "type": [ "string", "null" ], "example": "foo" }, "quantity": { "type": "string", "example": "1.0" }, "discount": { "type": "number", "example": 0 }, "subtotal": { "type": "number", "example": 1 }, "tax_amount": { "type": "number", "example": 0.07 }, "discount_amount": { "type": "number", "example": 0 }, "total": { "type": "number", "example": 1.07 }, "tax": { "type": "object", "properties": { "id": { "type": "integer", "example": 31597 }, "name": { "type": "string", "example": "IVA7" }, "value": { "type": "number", "example": 7 } } } } } } } } } } }, "422GeneratePayment": { "type": "array", "description": "List of `[field, message]` pairs.", "items": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 2 }, "example": [ [ "payment_mechanism", "is invalid" ], [ "amount", "must be less than or equal to 6.15" ] ] }, "422CancelPayment": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string", "example": "CantHandle: 1 for Invoice" } } } } } }, "EstimatesListAll": { "type": "object", "properties": { "estimates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 541791 }, "status": { "type": "string", "example": "final" }, "archived": { "type": "boolean", "example": false }, "type": { "type": "string", "enum": [ "Quote", "Proforma", "FeesNote" ], "example": "Quote" }, "sequence_number": { "type": "string", "example": "1/A" }, "inverted_sequence_number": { "type": "string", "example": "A/1" }, "atcud": { "type": "string", "example": "ABCD1234-1" }, "date": { "type": "string", "example": "12/06/2017" }, "due_date": { "type": "string", "example": "12/06/2017" }, "reference": { "type": [ "string", "null" ], "example": "foo", "maxLength": 255 }, "observations": { "type": [ "string", "null" ], "example": "foo", "description": "No enforced character limit (text column)." }, "retention": { "type": [ "string", "null" ], "example": null }, "permalink": { "type": "string", "example": "https://web.invoicexpress.com/documents/541791f16ae45a73b703c684a221ef198c10020f3d56a1" }, "saft_hash": { "type": "string", "example": "NfTN", "description": "Server-generated. No enforced character limit (text column)." }, "sum": { "type": "number", "example": 10 }, "discount": { "type": "number", "example": 0 }, "before_taxes": { "type": "number", "example": 10 }, "taxes": { "type": "number", "example": 2.3 }, "total": { "type": "number", "example": 12.3 }, "currency": { "type": "string", "example": "Euro" }, "sequence_id": { "type": [ "integer", "null" ], "example": 12345 }, "tax_exemption": { "type": "string", "example": "M01", "maxLength": 255 }, "cancel_reason": { "type": "string", "description": "Only present when the document is canceled.", "example": "Wrong client" }, "mb_reference": { "$ref": "#/components/schemas/MbReference", "description": "Only present when the document is final and has an MB reference." }, "multicurrency": { "type": "object", "description": "Only present for documents in a foreign currency.", "properties": { "rate": { "type": "number", "example": 1.1 }, "currency": { "type": "string", "example": "USD" }, "total": { "type": "number", "example": 13.53 } } }, "client": { "type": "object", "properties": { "id": { "type": "integer", "example": 1310176 }, "name": { "type": "string", "example": "John" }, "code": { "type": [ "string", "null" ], "example": "CLI-001" }, "email": { "type": [ "string", "null" ], "example": "john@example.com" }, "address": { "type": [ "string", "null" ], "example": "Avenida da República, Lisboa" }, "postal_code": { "type": [ "string", "null" ], "example": "1050-555" }, "city": { "type": [ "string", "null" ], "example": "Lisboa" }, "fiscal_id": { "type": [ "string", "null" ], "example": "508025338" }, "country": { "type": "string", "example": "Portugal" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "iPhone" }, "description": { "type": [ "string", "null" ], "example": "foo" }, "unit_price": { "type": "string", "example": "10.0" }, "unit": { "type": [ "string", "null" ], "example": "foo" }, "quantity": { "type": "string", "example": "1.0" }, "discount": { "type": "number", "example": 0 }, "subtotal": { "type": "number", "example": 10 }, "tax_amount": { "type": "number", "example": 2.3 }, "discount_amount": { "type": "number", "example": 0 }, "total": { "type": "number", "example": 12.3 }, "tax": { "type": "object", "properties": { "id": { "type": "integer", "example": 31567 }, "name": { "type": [ "string", "null" ], "description": "Null when the line has no tax assigned.", "example": "IVA23" }, "value": { "type": "number", "example": 23 } } } } } } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "422SendEmail": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string", "example": "Email is a required field" } } } } } }, "403SendEmail": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string", "example": "Email service is disabled for your account. To activate it, please contact us at support@invoicexpress.com." } } } } } }, "QueryParamns": { "type": "object", "properties": { "type[]": { "type": "array", "items": { "type": "string", "enum": [ "Invoice", "InvoiceReceipt", "SimplifiedInvoice", "CreditNote", "DebitNote", "Receipt", "CashInvoice", "VatMossInvoice", "VatMossCreditNote" ] }, "example": [ "Invoice" ], "description": "Type(s) of document. Optional: when omitted, every type except `Receipt` is returned." }, "status[]": { "type": "array", "items": { "type": "string", "enum": [ "draft", "sent", "settled", "canceled", "second_copy", "deleted" ] }, "example": [ "sent" ], "description": "Status(es) of document. Optional: when omitted, `draft`, `sent`, `settled`, `canceled` and `second_copy` are returned." }, "non_archived": { "type": "boolean", "example": true, "description": "Show non-archived documents. Optional: when no archived flag is sent, only non-archived documents are returned." }, "archived": { "type": "boolean", "description": "Include archived docs" }, "text": { "type": "string", "description": "Filter by client/doc text" }, "reference": { "type": "string", "description": "Filter by reference" }, "date[from]": { "type": "string", "description": "Start date (dd/mm/yyyy or yyyy-mm-dd)" }, "date[to]": { "type": "string", "description": "End date (dd/mm/yyyy or yyyy-mm-dd)" }, "due_date[from]": { "type": "string", "description": "Due date start" }, "due_date[to]": { "type": "string", "description": "Due date end" }, "total_before_taxes[from]": { "type": "number", "description": "Min value" }, "total_before_taxes[to]": { "type": "number", "description": "Max value" }, "total_with_taxes[from]": { "type": "number", "description": "Min value with taxes" }, "total_with_taxes[to]": { "type": "number", "description": "Max value with taxes" }, "client_id[]": { "type": "array", "items": { "type": "integer" }, "description": "Client ID(s)." }, "id[]": { "type": "array", "items": { "type": "integer" }, "description": "Only these document IDs." }, "except_id[]": { "type": "array", "items": { "type": "integer" }, "description": "Exclude these document IDs." }, "serie_name[]": { "type": "array", "items": { "type": "string" }, "description": "Sequence (series) name(s)." }, "sort": { "type": "string", "enum": [ "document_type", "client_name", "document_date", "document_due_date", "document_total_before_taxes", "document_total_with_taxes", "document_sequence_number", "document_status" ], "description": "Field to sort by. Only applied together with `sort_order`." }, "sort_order": { "type": "string", "enum": [ "ASC", "DESC" ], "description": "Sort direction. Only applied together with `sort`. Without both, results are ordered by date descending (guides: `loaded_at` descending)." }, "page": { "type": "integer", "description": "Page number" }, "per_page": { "type": "integer", "description": "Items per page. Defaults to 10. `items_per_page` is accepted as an alias." } } }, "DocumentClientRequest": { "type": "object", "description": "Client Details. To identify an existing client, send `id`, `code`, or `name` — not all three are required. Resolution priority: if `id` is sent and matches a client on the account, that client is used and `name`/`code` are ignored. Without `id`, if `code` matches an existing client, that client is used and `name` is not needed. Without an `id`/`code` match, `name` is used to find or create the client. Creating a brand-new client (no `id`/`code` match) still requires `name`; `code` is always optional and is never generated automatically by InvoiceXpress.", "properties": { "id": { "type": "integer", "example": 1310176, "description": "Internal client ID. Preferred way to identify an existing client — see schema description." }, "name": { "type": "string", "example": "Client A", "maxLength": 100 }, "code": { "type": "string", "example": "CLI-001", "maxLength": 255, "description": "Maximum length is the database default, not a business rule." }, "email": { "type": "string", "example": "client@mail.com", "maxLength": 254 }, "address": { "type": "string", "example": "Street A", "description": "No enforced character limit." }, "city": { "type": "string", "example": "Lisbon", "maxLength": 255, "description": "Maximum length is the database default, not a business rule." }, "postal_code": { "type": "string", "example": "1000-100", "maxLength": 255, "description": "Maximum length is the database default, not a business rule." }, "fiscal_id": { "type": "string", "example": "500999888", "maxLength": 255, "description": "Maximum length is the database default, not a business rule." }, "country": { "type": "string", "example": "Portugal", "maxLength": 255, "description": "Maximum length is the database default, not a business rule." }, "website": { "type": "string", "example": "www.client-a.com", "maxLength": 60 }, "phone": { "type": "string", "example": "912345678", "maxLength": 20 }, "fax": { "type": "string", "example": "212345678", "maxLength": 20 }, "observations": { "type": "string", "example": "VIP Client", "description": "No enforced character limit." } } }, "InvoiceTaxRequest": { "type": "object", "properties": { "name": { "type": "string", "example": "IVA23", "maxLength": 255, "description": "Maximum length is the database default, not a business rule." }, "value": { "type": "number", "example": 23, "description": "Tax rate (%). Alternative to `name`." } } }, "InvoiceItemRequest": { "type": "object", "description": "Line Item.", "required": [ "name", "unit_price", "quantity" ], "properties": { "name": { "type": "string", "example": "Consulting", "maxLength": 60, "description": "Maximum 60 characters. The V2 API silently truncates longer values to 60; the V3 API rejects them with 422." }, "description": { "type": "string", "example": "IT Services", "maxLength": 200, "description": "Maximum 200 characters and 20 lines. The V2 API silently truncates longer values to 200; the V3 API rejects them with 422." }, "unit_price": { "type": "number", "example": 50 }, "quantity": { "type": "number", "example": 2 }, "unit": { "type": "string", "example": "hour", "description": "Not a length limit — constrained to a fixed set of unit values." }, "discount": { "type": "number", "example": 0 }, "tax": { "$ref": "#/components/schemas/InvoiceTaxRequest" }, "retention": { "type": "number", "example": 25, "description": "Item retention rate (%)." } } }, "GlobalDiscountRequest": { "type": "object", "properties": { "value_type": { "type": "string", "enum": [ "percentage", "absolute" ], "example": "percentage" }, "value": { "type": "number", "example": 10 } } }, "CreateBody": { "type": "object", "description": "Invoice Body. The root key can be `invoice` or the singular of the requested `{invoices-type}` (`invoice_receipt`, `simplified_invoice`, `credit_note`, `debit_note`).", "properties": { "date": { "type": "string", "example": "22/11/2025", "description": "dd/mm/yyyy" }, "due_date": { "type": "string", "example": "22/12/2025", "description": "dd/mm/yyyy. Defaults to `date` when omitted." }, "reference": { "type": "string", "example": "PO-999", "maxLength": 255 }, "observations": { "type": "string", "example": "Services rendered", "description": "No enforced character limit." }, "retention": { "type": "string", "example": "0" }, "tax_exemption": { "type": "string", "example": "M00", "maxLength": 255, "description": "Maximum length is the database default, not a business rule — the value is effectively an AT exemption code." }, "sequence_id": { "type": "string", "example": "123456" }, "manual_sequence_number": { "type": "string", "maxLength": 255, "description": "Maximum length is the database default, not a business rule." }, "client": { "$ref": "#/components/schemas/DocumentClientRequest" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceItemRequest" } }, "mb_reference": { "type": "string", "enum": [ "0", "1" ], "example": "1" }, "owner_invoice_id": { "type": "integer", "example": 1049 }, "tax_exemption_reason": { "type": "string", "example": "M00", "maxLength": 210, "description": "Maximum 210 characters. Enforced by model validation — longer values are rejected with 422 even though the underlying column would accept more." }, "currency_code": { "type": "string", "example": "USD" }, "rate": { "type": "string", "example": "1.10" }, "plugin_id": { "type": "string", "example": "plugin_123" }, "global_discount": { "$ref": "#/components/schemas/GlobalDiscountRequest" }, "proprietary_uid": { "type": "string", "example": "uuid-123", "description": "Idempotency key, same as the top-level `proprietary_uid`." }, "tax_exemption_code": { "type": "string", "example": "M07", "description": "Tax exemption code." }, "tax_exemption_message": { "type": "string", "example": "Isento artigo 9.º do CIVA", "description": "Tax exemption message." }, "discount": { "type": "number", "example": 0, "description": "Document discount." }, "raw_owner_invoice": { "description": "Credit and debit notes only. Reference to an original document issued outside InvoiceXpress. Send a string, or an object with `document_type`, `document_serie` and `document_number`. Cannot be combined with `owner_invoice_id`.", "oneOf": [ { "type": "string", "example": "FT A/123" }, { "type": "object", "properties": { "document_type": { "type": "string", "example": "FT" }, "document_serie": { "type": "string", "example": "A" }, "document_number": { "type": "string", "example": "123" } } } ] } } }, "EstimateFilters": { "type": "object", "required": [ "type[]", "status[]", "non_archived" ], "properties": { "type[]": { "type": "array", "items": { "type": "string", "enum": [ "Quote", "Proforma", "FeesNote" ] }, "example": [ "Quote" ], "description": "Type(s) of document." }, "status[]": { "type": "array", "items": { "type": "string", "enum": [ "draft", "sent", "accepted", "refused", "canceled", "deleted" ] }, "example": [ "sent" ], "description": "Status(es) of document." }, "non_archived": { "type": "boolean", "example": true, "description": "Show non-archived documents." }, "archived": { "type": "boolean", "description": "Include archived docs" }, "text": { "type": "string", "description": "Filter by client/doc text" }, "valid_to[from]": { "type": "string", "description": "Validity date start (dd/mm/yyyy)" }, "valid_to[to]": { "type": "string", "description": "Validity date end (dd/mm/yyyy)" }, "date[from]": { "type": "string", "description": "Start date (dd/mm/yyyy or yyyy-mm-dd)" }, "date[to]": { "type": "string", "description": "End date (dd/mm/yyyy or yyyy-mm-dd)" }, "total_before_taxes[from]": { "type": "number", "description": "Min value" }, "total_before_taxes[to]": { "type": "number", "description": "Max value" }, "total_with_taxes[from]": { "type": "number", "description": "Min value with taxes" }, "total_with_taxes[to]": { "type": "number", "description": "Max value with taxes" }, "client_id[]": { "type": "array", "items": { "type": "integer" }, "description": "Client ID(s)." }, "sort": { "type": "string", "enum": [ "document_type", "client_name", "document_date", "document_valid_until", "document_total_before_taxes", "document_total_with_taxes", "document_sequence_number", "document_status" ], "description": "Field to sort by. Only applied together with `sort_order`." }, "sort_order": { "type": "string", "enum": [ "ASC", "DESC" ], "description": "Sort direction. Only applied together with `sort`. Without both, results are ordered by date descending (guides: `loaded_at` descending)." }, "page": { "type": "integer", "description": "Page number" }, "per_page": { "type": "integer", "description": "Items per page. Defaults to 10. `items_per_page` is accepted as an alias." } } }, "GuideQueryParamns": { "type": "object", "required": [ "type[]", "status[]", "non_archived" ], "properties": { "text": { "type": "string", "description": "Search for guide, client or item details." }, "type[]": { "type": "array", "items": { "type": "string", "enum": [ "Shipping", "Transport", "Devolution" ] }, "example": [ "Shipping" ], "description": "Type(s) of document." }, "status[]": { "type": "array", "items": { "type": "string", "enum": [ "draft", "sent", "canceled", "second_copy" ] }, "example": [ "sent" ], "description": "Status(es) of document." }, "non_archived": { "type": "boolean", "example": true, "description": "Show non-archived documents." }, "archived": { "type": "boolean", "description": "Include archived docs" }, "loaded_at[from]": { "type": "string", "description": "Date in format dd/mm/yyyy." }, "loaded_at[to]": { "type": "string", "description": "Date in format dd/mm/yyyy." }, "date[from]": { "type": "string", "description": "Start date (dd/mm/yyyy)" }, "date[to]": { "type": "string", "description": "End date (dd/mm/yyyy)" }, "client_id[]": { "type": "array", "items": { "type": "integer" }, "description": "Client ID(s)." }, "total_before_taxes[from]": { "type": "number", "description": "Min value before taxes" }, "total_before_taxes[to]": { "type": "number", "description": "Max value before taxes" }, "total_with_taxes[from]": { "type": "number", "description": "Min value with taxes" }, "total_with_taxes[to]": { "type": "number", "description": "Max value with taxes" }, "sort": { "type": "string", "enum": [ "client_name", "document_loaded_at", "document_type", "document_status", "document_sequence_number", "document_total_before_taxes", "document_total_with_taxes" ], "description": "Field to sort by. Only applied together with `sort_order`." }, "sort_order": { "type": "string", "enum": [ "ASC", "DESC" ], "description": "Sort direction. Only applied together with `sort`. Without both, results are ordered by date descending (guides: `loaded_at` descending)." }, "page": { "type": "integer", "description": "Page number" }, "per_page": { "type": "integer", "description": "Items per page" } } }, "GuideListAll": { "type": "object", "properties": { "guides": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 541797 }, "status": { "type": "string", "example": "final" }, "archived": { "type": "boolean", "example": false }, "type": { "type": "string", "example": "Shipping" }, "sequence_number": { "type": "string", "example": "1/D" }, "inverted_sequence_number": { "type": "string", "description": "Only present once the guide has been finalized.", "example": "D/1" }, "atcud": { "type": "string", "example": "ABCD1234-1" }, "date": { "type": "string", "description": "dd/mm/yyyy", "example": "13/07/2017" }, "due_date": { "type": "string", "description": "dd/mm/yyyy", "example": "13/07/2017" }, "reference": { "type": [ "string", "null" ], "example": null, "maxLength": 255 }, "observations": { "type": [ "string", "null" ], "example": null, "description": "No enforced character limit (text column)." }, "retention": { "type": [ "string", "null" ], "example": null }, "permalink": { "type": "string", "example": "https://web.invoicexpress.com/documents/541797d75bbee48911934cbd4a4294946a324295f52b08" }, "saft_hash": { "type": "string", "description": "Only present once the guide has been finalized.", "example": "vaDf" }, "sum": { "type": "number", "example": 1 }, "discount": { "type": "number", "example": 0 }, "before_taxes": { "type": "number", "example": 1 }, "taxes": { "type": "number", "example": 0.07 }, "total": { "type": "number", "example": 1.07 }, "currency": { "type": "string", "example": "Euro" }, "loaded_at": { "type": "string", "description": "dd/mm/yyyy. Note the single-guide endpoint returns this same field with a time component (dd/mm/yyyy HH:mm:ss).", "example": "27/07/2026" }, "license_plate": { "type": [ "string", "null" ], "example": "11-AA-22", "maxLength": 255, "description": "255-character limit is the database column default, not an explicit business rule." }, "at_doc_code_id": { "type": [ "string", "null" ], "example": "999", "maxLength": 255, "readOnly": true, "description": "Read-only. Written only by the AT gateway and never accepted on input. The 255-character limit is the database column default, not an explicit business rule." }, "sequence_id": { "type": [ "integer", "null" ], "description": "Only present once the guide has been finalized.", "example": 12345 }, "tax_exemption": { "type": "string", "example": "M01" }, "address_from": { "type": "object", "properties": { "country": { "type": "string", "example": "Portugal", "maxLength": 255, "description": "Not stored on the address itself — resolved through a tax-location name lookup, falling back to Portugal." }, "postal_code": { "type": "string", "example": "1050-083", "maxLength": 255, "description": "255-character limit is the database column default on the Address model, not an explicit business rule." }, "detail": { "type": "string", "example": "Avenida Duque D'Avila, 46 - 3ºA", "maxLength": 255, "description": "255-character limit is the database column default on the Address model, not an explicit business rule. Note the API re-inserts line breaks roughly every 35 characters before storing, so an input close to 255 characters can overflow the column — keep well under the limit." }, "city": { "type": "string", "example": "Lisboa", "maxLength": 255, "description": "255-character limit is the database column default on the Address model, not an explicit business rule." } } }, "address_to": { "type": "object", "properties": { "country": { "type": "string", "example": "Portugal", "maxLength": 255, "description": "Not stored on the address itself — resolved through a tax-location name lookup, falling back to Portugal." }, "postal_code": { "type": "string", "example": "4000-327", "maxLength": 255, "description": "255-character limit is the database column default on the Address model, not an explicit business rule." }, "detail": { "type": "string", "example": "Avenida dos Aliados", "maxLength": 255, "description": "255-character limit is the database column default on the Address model, not an explicit business rule. Note the API re-inserts line breaks roughly every 35 characters before storing, so an input close to 255 characters can overflow the column — keep well under the limit." }, "city": { "type": "string", "example": "Porto", "maxLength": 255, "description": "255-character limit is the database column default on the Address model, not an explicit business rule." } } }, "load_site": { "type": [ "string", "null" ], "description": "Flattened `address_from` (detail, postal code, city, country). Null when not set.", "example": "Avenida Duque D'Avila, 1050-083 Lisboa, Portugal" }, "delivery_site": { "type": [ "string", "null" ], "description": "Flattened `address_to` (detail, postal code, city, country). Null when not set.", "example": "Avenida dos Aliados, 4000-327 Porto, Portugal" }, "client": { "type": "object", "description": "Only `id` and `name` are guaranteed; the remaining fields are present when set on the client record.", "properties": { "id": { "type": "integer", "example": 1310176 }, "name": { "type": "string", "example": "John", "maxLength": 100 }, "code": { "type": [ "string", "null" ], "example": "CLI-001", "maxLength": 255, "description": "255-character limit is the database column default, not an explicit business rule." }, "email": { "type": [ "string", "null" ], "example": "john@example.com", "maxLength": 254 }, "address": { "type": [ "string", "null" ], "example": "Avenida da República, Lisboa", "description": "No enforced character limit (text column)." }, "postal_code": { "type": [ "string", "null" ], "example": "1050-555", "maxLength": 255, "description": "255-character limit is the database column default, not an explicit business rule." }, "city": { "type": [ "string", "null" ], "example": "Lisboa", "maxLength": 255, "description": "255-character limit is the database column default, not an explicit business rule." }, "fiscal_id": { "type": [ "string", "null" ], "example": "508025338", "maxLength": 255, "description": "255-character limit is the database column default, not an explicit business rule." }, "country": { "type": "string", "example": "Portugal", "maxLength": 255, "description": "255-character limit is the database column default, not an explicit business rule." } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "iPhone", "maxLength": 60, "description": "Maximum 60 characters. V3 rejects a longer name with HTTP 422; V2 accepts the request and silently truncates the stored value to 60 characters." }, "description": { "type": [ "string", "null" ], "example": null, "maxLength": 200, "description": "Maximum 200 characters and 20 lines. V3 rejects a longer description with HTTP 422; V2 accepts the request and silently truncates the stored value to 200 characters." }, "unit_price": { "type": "string", "example": "1.0" }, "unit": { "type": [ "string", "null" ], "example": "service", "description": "Restricted to a fixed set of unit values rather than length-limited free text." }, "quantity": { "type": "string", "example": "1.0" }, "tax": { "type": "object", "properties": { "id": { "type": "integer", "example": 31597 }, "name": { "type": "string", "example": "IVA7" }, "value": { "type": "number", "example": 7 } } }, "discount": { "type": "number", "example": 0 }, "subtotal": { "type": "number", "example": 1 }, "tax_amount": { "type": "number", "example": 0.07 }, "discount_amount": { "type": "number", "example": 0 }, "total": { "type": "number", "example": 1.07 } } } } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "SaftExportParams": { "type": "object", "required": [ "month", "year" ], "properties": { "month": { "type": "string", "description": "The month for which you want to generate the SAF-T.", "example": "10" }, "year": { "type": "string", "description": "The year for which you want to generate the SAF-T.", "example": "2017" } } } } } }