Fakturaer

Hente fakturaliste

Du henter en liste med dine fakturaer slik:

GET /api/v1/invoices

Eksempel på respons:

<?xml version="1.0" encoding="utf-8"?>
<invoices page="1" total_pages="2" per_page="100">
  <invoice uri="https://app.fakturo.no/api/v1/invoice/671" status="overdue">
    <invoice_number>117</invoice_number>
    <issue_date>2011-06-16</issue_date>
    <due_date>2011-06-16</due_date>
    <gross_amount>16675.00</gross_amount>
    <net_amount>13340.00</net_amount>
  </invoice>
  <invoice uri="https://app.fakturo.no/api/v1/invoice/670" status="paid">
    <invoice_number>116</invoice_number>
    <issue_date>2011-05-17</issue_date>
    <due_date>2011-05-17</due_date>
    <gross_amount>1537.50</gross_amount>
    <net_amount>1230.00</net_amount>
  </invoice>
  <!-- mange flere invoice her  -->
</invoices>

Url-parametere

Du kan filtrere listen med fakturaer ved å legge til ulike URL-parametere.

Parametrene som kan brukes er:

URL-parameter Forklaring
search Søk på fakturanummer eller fakturamottakers navn.
from_date Fakturadato fra og med denne datoen (format: yyyy-mm-dd)
to_date Fakturadato til og med denne datoen (format yyyy-mm-dd)
status Filter på fakturastatus (se tabellen nedenfor for mulige verdier).

Eksempel: Søk etter fakturaer til "Hansen" mellom 01.01.2011 og 01.06.2011 som har forfalt:

GET /api/v1/invoices?search=Hansen&from_date=2011-01-01&to_date=2011-06-01&status=overdue

Filtrer på status

URL-parameteren status kan brukes til å bare hente ut fakturaer med en gitt status. Det kan være nyttig når du har mange fakturaer, og vet hvilke typer du ønsker returnert.

Verdiene som kan brukes og som returneres i listen

Filter Forklaring
all Alle fakturaer (samme som å ikke oppgi filter)
invoice_sent Fakturaen er sendt, men ikke forfalt.
invoice_paid Fakturaen er betalt
invoice_overdue Fakturaen har forfalt, men purregebyr kan ikke legges til
invoice_overdue_chargeable Fakturaen har forfalt, og purregebyr kan legges til
overdue_notice_sent Fakturaen er purret, men purringen har ikke forfalt ennå.
overdue_notice_overdue Fakturaen er purret, og purringen har forfalt
debt_collection_notice_sent Det er sendt inkassovarsel, men inkassovarselet har ikke forfalt
debt_collection_notice_overdue Det er sendt inkassovarse, og inkassovarselet har forfalt.
debt_collection Fakturaen er overført til inkasso
closed_lost Fakturaen er lukket (manuelt) og merket som tap
closed_other Fakturaen er lukket (manuelt) av andre grunner

I tillegg til statusene over, kan du bruke meta-statuser som kombinerer flere av statusene over:

Filter Forklaring
overdue Alle fakturaer hvor enten fakturaen selv, purring eller inkassovarsel har forfalt.
waiting Alle fakturaer hvor enten faktura, purring eller inkassovarsel ikke har forfalt

Eksempel: Hent ut alle fakturaer som kan sendes til inkasso:

GET /api/v1/invoices?status=debt_collection_notice_overdue

Du kan også kombinere flere statuser ved å skille med pipe-tegnet (|):

GET /api/v1/invoices?status=invoice_sent|invoice_paid

Hente fakturadetaljer

For å hente alle detaljer om en enkelt faktura, bruker du:

GET /api/v1/invoice/:id

Responsen inneholder blant annet fakturalinjer, mottaker, innbetalinger, purringer og kreditnotaer for denne fakturaen:

<?xml version="1.0" encoding="utf-8"?>
<invoice uri="https://app.fakturo.no/api/v1/invoice/123">
  <invoice_number>116</invoice_number>     <!-- fakturanummer -->
  <issue_date>2011-05-17</issue_date>      <!-- fakturadato -->
  <due_date>2011-05-17</due_date>          <!-- forfallsdato -->
  <num_due_days>20</num_due_days>          <!-- antall forfallsdager -->
  <gross_amount>1537.50</gross_amount>     <!-- bruttobeløp (inkl mva) -->
  <net_amount>1230.00</net_amount>         <!-- nettobeløp (eks mva) -->
  <invoice_note>Denne fakturaen gjelder konsulenttjenester utført i mai
    2011
  </invoice_note>
  <ocr_kid_number>1235266</ocr_kid_number> <!-- KID-nummer -->
  <recipient>
    <!-- parent_recipient peker til nåværende kundeobjekt. Det kan være oppdatert 
      siden fakturaen ble sendt. -->
    <parent_recipient uri="https://app.fakturo.no/api/v1/customer/456" />
    <!-- Dataene nedenfor er kundeopplysningene slik de var da fakturaen 
      ble sendt. -->
    <name1>Min Mottaker AS</name1>
    <name2>Test Person</name2>
    <address1>Test Adresse 1</address1>
    <address2></address2>
    <postal_code>0656</postal_code>
    <postal_name>OSLO</postal_name>
    <email></email>
    <customer_number>12120</customer_number>
    <country_code>NO</country_code>
  </recipient>
  <!-- Fakturalinjer nedenfor -->
  <lines>
    <line index="1">
      <line_text>Bananer og epler</line_text>
      <unit_price>123</unit_price>
      <num_items>10</num_items>
      <discount_percent></discount_percent>
      <net_amount>1230.00</net_amount>
      <gross_amount>1537.50</gross_amount>
      <vat_rate percent="25">HIGH</vat_rate> <!-- HIGH=25%, MEDIUM=15%, LOW=8%, NONE=ingen mva -->
    </line>
    <line index="2">
      <line_text>Purregebyr ubetalt fra forrige faktura</line_text>
      <unit_price>61</unit_price>
      <num_items>1</num_items>
      <discount_percent></discount_percent>
      <net_amount>61.00</net_amount>
      <gross_amount>61.00</gross_amount>
      <vat_rate percent="0">NONE</vat_rate>
    </line>
  </lines>
  <!-- Informasjon om når og hvordan fakturaen ble sendt. -->
  <shipments>
    <shipment type="original">
      <shipment_method>PAPER</shipment_method>
      <sent_at>2011-09-01 12:45:59</sent_at>
      <recipient>
        <name1>TestFirma a244d AS</name1>
        <name2>Test Person</name2>
        <address1>Test Adresse 1</address1>
        <address2></address2>
        <postal_code>0656</postal_code>
        <postal_name>OSLO</postal_name>
        <email>example@example.org</email>
        <customer_number></customer_number>
        <country_code>NO</country_code>
      </recipient>
    </shipment>
    <shipment type="copy">
      <shipment_method>EMAIL</shipment_method>
      <sent_at>2011-09-01 12:45:59</sent_at>
      <recipient>
        <email>kopi@example.org</email>
      </recipient>
    </shipment>
    <shipment type="copy">
      <shipment_method>EMAIL</shipment_method>
      <sent_at>2011-09-01 12:45:59</sent_at>
      <recipient>
        <email>kopi2@example.org</email>
      </recipient>
    </shipment>   
  </shipments>
  <!--  Saldotransaksjoner for denne fakturaen -->
  <ar_transactions balance="0.00"><!--  Angir balance for denne fakturaen -->
    <ar_transaction uri="https://app.fakturo.no/api/v1/ar_transaction/555">
      <transaction_date>2011-06-06</transaction_date>
      <amount>1537.50</amount>
      <comment></comment>
      <from_account_number></from_account_number>
      <transaction_type>INVOICE</transaction_type>
    </ar_transaction>
    <ar_transaction uri="https://app.fakturo.no/api/v1/ar_transaction/557">
      <transaction_date>2011-06-06</transaction_date>     <!-- Transaksjonsdato -->
      <amount>61.00</amount>                              <!-- Beløp -->
      <comment></comment>                                 <!-- Kommentar -->
      <from_account_number></from_account_number>         <!-- Innbetalt fra konto (kun for OCR) -->
      <transaction_type>OVERDUE_CHARGE</transaction_type> <!-- Type transaksjon (se under) -->
    </ar_transaction>
    <ar_transaction uri="https://app.fakturo.no/api/v1/ar_transaction/558">
      <transaction_date>2011-06-06</transaction_date>
      <amount>7.58</amount>
      <comment>For perioden 17.05. - 05.06.11</comment>
      <from_account_number></from_account_number>
      <transaction_type>INTEREST</transaction_type>
    </ar_transaction>
    <ar_transaction uri="https://app.fakturo.no/api/v1/ar_transaction/561">
      <transaction_date>2011-06-10</transaction_date>
      <amount>-1606.08</amount>
      <comment>Kunde betalte til bankkonto</comment>
      <from_account_number></from_account_number>
      <transaction_type>PAYMENT</transaction_type>
    </ar_transaction>
  </ar_transactions>
  <!-- eventuelle purringer for denne fakturaen -->
  <overdue_notices>  
    <overdue_notice uri="https://app.fakturo.no/api/v1/overdue_notice/673">
      <issue_date>2011-06-06</issue_date>
      <due_date>2011-06-20</due_date>
      <gross_amount>1606.08</gross_amount>
      <is_incasso_notice>1</is_incasso_notice> <!-- 1 hvis inkassovarsel, 0 ellers -->
      <sequence_number>1</sequence_number>     <!-- Rekkefølge på purring, 1 eller 2 -->
    </overdue_notice>
  </overdue_notices>
  <credit_notes /> <!-- eventuelle kreditnotaer for denne fakturaen -->
</invoice>

Lage og sende en faktura

Du oppretter og sender en ny faktura slik:

POST /api/v1/invoices

Dataene du sender inn via POST må være en XML med minst én fakturalinje, antall dager til forfall, hvordan du vil sende fakturaen, og mottaker.

Hvis alt går bra, returneres HTTP-responskoden 201 Created sammen med en Location-header som er URL til den nye fakturaen som er opprettet.

Eksempel 1: Ny faktura til eksisterende kunde

Dette viser hvilke data du minimum må sende inn for å lage en ny faktura.

<invoice>
  <num_due_days>20</num_due_days>        <!-- Antall dager til forfall -->
  

  <!-- For å bruke en eksisterende kunde, oppgir vi URL slik: -->
  <recipient uri="https://app.fakturo.no/api/v1/customer/848" />
  
  <!-- Fakturalinjer -->
  <lines>
    <line>
      <line_text>Gull, røkelse og myrra</line_text>
      <unit_price>19988.00</unit_price>
      <num_items>2</num_items>
      <vat_rate>HIGH</vat_rate>
    </line>
  </lines>

  <!--  Hvordan fakturaen skal sendes -->
  <shipments>
    <!--  Adresse / e-post for originalmottaker hentes fra oppgitt recipient -->
    <shipment type="original">
      <shipment_method>PAPER</shipment_method> <!--  PAPER eller EMAIL  -->
    </shipment>
  </shipments>
  
</invoice>

Dersom du venter å sende som EMAIL må kunden ha utfylt e-postadresse. Hvis ikke må du oppdatere kundeobjektet først.

Eksempel 2: Ny faktura til ny kunde

I dette tilfellet vil det bli opprettet en ny kunde. Vi anbefaler at du sjekker om du allerede har registrert en kunde, ellers vil det etterhvert bli mange like kundeobjekter på kontoen din.

<invoice>

  <num_due_days>20</num_due_days>
  <invoice_note>Fakturaen gjelder tjenester levert i desember år 0.
  </invoice_note>

  <!-- Dette oppretter en ny kunde -->
  <recipient>
    <name1>Min Nye Kunde AS</name1>
    <address1>Øvre gate 14</address1>
    <postal_code>1212</postal_code>
    <postal_name>OSLO</postal_name>
  </recipient>

  <!-- Du kan oppgi inntil 8 fakturalinjer -->
  <lines>
    <line>
      <line_text>Gull, røkelse og myrra</line_text>
      <unit_price>19988.00</unit_price>
      <num_items>2</num_items>
      <vat_rate>HIGH</vat_rate>
    </line>
  </lines>

  <shipments>
  
    <shipment type="original">
      <shipment_method>EMAIL</shipment_method>
    </shipment>
  
    <shipment type="copy">
      <shipment_method>EMAIL</shipment_method>
      <recipient>
        <email>myself@example.org</email>
      </recipient>
    </shipment>
  
  </shipments>

</invoice>

Oppdatere en faktura

Ikke tilgjengelig

Du kan ikke oppdatere en faktura.

Slette en faktura

Ikke tilgjengelig

Du kan ikke slette en faktura på grunn av kravene til løpende fakturanummerserie. Hvis du ønsker å rette opp en feil på en faktura som er sendt, må du sende en kreditnota.

Laste ned faktura som PDF

Du kan hente ned PDF-dokumentet for en faktura (med eventuelle vedlegg) slik:

GET /api/v1/invoice/123/pdf

Dette metoden returnerer ikke XML, men i stedet PDF-data levert med Content-Type application/pdf.

Nedlasting av purringer og kreditnotaer gjøres på tilvarende måte, men med overdue_notice eller credit_note i URLen i stedet for invoice.

Opp til toppen av siden